Category: Oracle REST Data Services

8080 is already in use

When trying to start Oracle REST Data Services (ORDS), you may encounter the frustrating error message: “could not start standalone mode because the listen port: 8080 is already in use by another process. check if another instance of ords is already running“. This error indicates that another application or process is already using port 8080, preventing ORDS from starting successfully. In this article, we will guide you through the steps to identify the application using port 8080 on Windows, macOS, and Linux, allowing you to resolve this issue and get ORDS up and running.

Note that this can happen if you are trying to run multiple ORDS instances using HTTPS traffic. See Multiple ORDS Instances on the Same Machine for more information on that.

Find the Application Using Port 8080:

Windows:

  1. Open the Command Prompt: Press Win + R, type “cmd,” and hit Enter.
  2. In the Command Prompt, enter the following command: netstat -ano | findstr :8080.
  3. Identify the line with the local address 0.0.0.0:8080 or 127.0.0.1:8080 in the output.
  4. Take note of the PID (Process Identifier) associated with that line.
  5. Open the Task Manager: Press Ctrl + Shift + Esc.
  6. Go to the “Details” tab in the Task Manager.
  7. Locate the process with the corresponding PID from step 4 to identify the application using port 8080.

macOS:

  1. Open Terminal: Navigate to the Applications/Utilities folder or use Spotlight Search to find it.
  2. In the Terminal, enter the following command: lsof -i :8080.
  3. Look for the line with the local address *:8080 in the output.
  4. Note the PID associated with that line.
  5. Enter the command: ps -p [PID] -o comm= (replace [PID] with the PID noted in step 4).
  6. The output of the above command will display the name of the application using port 8080.
On my mac the output of the lsof command looks like this

Linux:

  1. Open a Terminal: Use a terminal application such as GNOME Terminal, Konsole, or xterm.
  2. In the terminal, enter the following command: sudo lsof -i :8080.
  3. Look for the line with the local address *:8080 in the output.
  4. Note the PID associated with that line.
  5. Enter the command: ps -p [PID] -o comm= (replace [PID] with the PID noted in step 4).
  6. The output of the above command will display the name of the application using port 8080.
On a linux machine this is the output of “lsof -i :9193” which shows docker containers using that port

Resolving the Issue:

Once you have identified the application or process using port 8080, you have a few options to resolve the issue:

  1. Terminate the Conflicting Application: If the application using port 8080 is not essential or can be temporarily shut down, you can terminate it from the Task Manager (Windows) or using the appropriate command for macOS or Linux.
  2. Change the ORDS Port: If terminating the conflicting application is not feasible, you can have ORDS use a different port that is not in use such as port 8081. This can be achieved in one of two ways:
    • On the command line when starting standalone: ords serve --port 8081
    • In the configuration: ords config set standalone.http.port 8081
  3. Configure the Conflicting Application: If the conflicting application is critical and cannot be terminated, you may need to adjust its configuration to use a different port, freeing up port 8080 for ORDS. Consult the documentation or support resources for the specific application to learn how to modify its port configuration.
Just one more thing…

Of course you can change port 8080 for any other port that you happen to want to use. Using the standard ports 80 and 443 can be problematic in that there might be a service already using that port and the above approaches to not always list these background services. For example, if you are using a container management system such as Rancher and have Traefik enabled, it will not be shown as listing on the port, but it will have your traffic redirected to it, and not your ORDS instance.

Conclusion

Hitting the “8080 is already in use by another process” error when starting Oracle REST Data Services (ORDS) can be frustrating, but by following the steps outlined in this article, you can identify the application using that port and take appropriate action to resolve the issue. Whether it involves terminating the conflicting application, changing the ORDS port, or configuring the conflicting application differently, you’ll soon have ORDS running smoothly.

ORDS, Database Vault and ORA-20031

Picture this…you’ve been working happily with ORDS for ages and realise that it’s time to upgrade but in your upgrade test environment you start seeing issues with ORDS not being able to create connections at runtime and nothing works!

No matter what you try to do, it’s ORA-20031: Management of Schema enablement has been restricted to ORDS_ADMINISTRATOR_ROLE privilege error messages everywhere!

It is not immediately obvious but the root cause is likely to be the Oracle Database Vault feature that has been doing such a good job in protecting data in the database. Database Vault is a security feature designed to provide additional layers of protection for sensitive data, and can enhance the security of data-driven applications. The sort of data-driven applications that one would use with ORDS. Users can encounter this hurdle while working with this combination of ORDS and Database Vault when upgrading ORDS. This happens especially when ORDS was initially installed first and then Database Vault enabled afterwards.

SQL> BEGIN

 ORDS.ENABLE_SCHEMA(p_enabled => TRUE,
    p_schema => ‘AVSYS’,
    p_url_mapping_type => ‘BASE_PATH’,
    p_url_mapping_pattern => ‘auditvault’,
    p_auto_rest_auth => FALSE);

 commit;
end;
/ 2  3  4  5  6  7  8  9  10  11
’BEGIN
*
ERROR at line 1:
ORA-20031: Management of Schema enablement has been restricted to
ORDS_ADMINISTRATOR_ROLE privilege.
ORA-06512: at “ORDS_METADATA.ORDS”, line 183
ORA-06512: at “ORDS_METADATA.ORDS_INTERNAL”, line 1048
ORA-01031: insufficient privileges
ORA-06512: at “ORDS_METADATA.ORDS_INTERNAL”, line 456
ORA-06512: at “ORDS_METADATA.ORDS_INTERNAL”, line 468
ORA-06512: at “ORDS_METADATA.ORDS_INTERNAL”, line 468
ORA-06512: at “ORDS_METADATA.ORDS_INTERNAL”, line 1034
ORA-06512: at “ORDS_METADATA.ORDS_INTERNAL”, line 922
ORA-06512: at “ORDS_METADATA.ORDS_INTERNAL”, line 1063
ORA-06512: at “ORDS_METADATA.ORDS”, line 167
ORA-06512: at line 3

When you see this error it’s because the database user is protected by Database Vault. The ORDS documentation does have a section about Authorizing Oracle REST Data Services to Access Protected Users but it does not specifically call out the error message you get when you don’t perform this additional authorisation step using DBMS_MACADM.AUTHORIZE_PROXY_USER

DBMS_MACADM.AUTHORIZE_PROXY_USER(
  proxy_user   IN VARCHAR2,
  user_name    IN VARCHAR2);

Conclusion

The upshot is that for every database user that you REST Enable, when using Oracle Database Vault, there’s an extra step:

BEGIN
  ORDS_ADMIN.ENABLE_SCHEMA(
    p_schema => 'tickets'
  );
  DBMS_MACADM.AUTHORIZE_PROXY_USER('ORDS_PUBLIC_USER','TICKETS');
END;
/

Note: In the majority of cases ORDS_PUBLIC_USER is the configured ORDS Runtime User specified by the db.username configuration setting.

Beyond the Common Name: Secure multiple domains with a single self-signed certificate

Oracle REST Data Services (ORDS) will generate a self-signed automatically when starting for the first time in standalone mode. That is, if it has not already been configured with an existing cert and key. The Common Name used for the self-signed certificate is taken from the standalone.https.host configuration setting. If not set, the value is localhost. Traditional certificate practices often rely solely on the Common Name (CN) field. That’s the approach taken by ORDS by default when generating the self-signed certificate. The upshot is that you are limited to one certificate for one domain. In this article, we explore the untapped potential of self-signed certificates with Subject Alternative Name (SAN) extension, enabling you to secure multiple domains efficiently

Understanding Self-Signed Certificates

Self-signed certificates are created and signed by the same entity without involving a trusted third-party Certificate Authority (CA). They provide encryption and authentication capabilities, although they are not initially recognised by most browsers and operating systems. Self-signed certificates can be manually trusted or imported, making them a viable option for specific use cases.

Subject Alternative Name (SAN)

SAN is an extension within the X.509 certificate standard that allows multiple domain names to be associated with a single certificate. Unlike the limited scope of the Common Name field, SAN enables you to secure multiple domains or subdomains with one certificate, simplifying management and reducing costs.

Benefits of Self-Signed Certificates with SAN

  • Enhanced Flexibility: Self-signed certificates with SAN offer the flexibility to secure numerous domains or subdomains, accommodating complex web architectures and diverse configurations.
  • Cost-Effectiveness: By leveraging self-signed certificates, you can save costs associated with purchasing individual certificates for each domain.
  • Internal Environments: Self-signed certificates with SAN are especially valuable for securing internal networks, intranets, or testing environments that don’t require public trust.
  • Rapid Deployment: Generating and deploying self-signed certificates with SAN is a swift and straightforward process, making it ideal for time-sensitive projects.

Considerations and Best Practices:

  • Trust Management: Users must manually trust self-signed certificates, so clear instructions or documentation on certificate importation are essential.
  • Certificate Lifecycle: Although self-signed certificates have no defined expiration period, regular rotation is recommended to uphold security best practices.
  • Public-Facing Websites: For public-facing websites, obtaining trusted certificates from recognised CAs is crucial to establish trust with visitors and avoid browser warnings.
  • Hybrid Approach: Consider combining self-signed certificates with SAN for internal domains and trusted CA certificates for public-facing domains to strike a balance between cost-efficiency and public trust.
  • Load Balancers: For public-facing websites, use a load balancer in front of your ORDS instance(s). That way you can aim for high availability but also configure single Common Name certs for public-facing services.

Generate your self-signed SAN cert…

Try saying that fast three times 😀

There’s no command in ORDS to generate self-signed certificate with a Subject Alternative Name ( SAN ) field. To achieve this we’ll use the openssl utility which is most likely already available on your machine. The example openssl command below can be executed where the ORDS configuration directory is the working directory. The output is two files with the same name as what ORDS uses as the default standalone.https.cert.key and standalone.https.cert configuration settings respectively. 

openssl req -x509 -nodes -days 365 \
       -newkey rsa:2048 \
       -keyout global/standalone/self-signed.key \
       -out global/standalone/self-signed.pem \
       -subj "/CN=localhost" \
       -addext "subjectAltName = DNS:vanity.example.com, DNS:myhost.example

In the above example the self-signed certificate is generated with localhost in the Common Name ( CN ) field. This is the same as the certificate that would normally be generated by ORDS. However, that certificate also has a subjectAltName field listing two DNS hostnames: vanity.example.com and myhost.example. Start up ORDS and your traffic to the server will be secured for both domains. Note that you will have to look after your DNS network routing so that the domain names you choose route to the machine you are running ORDS on.

That certificate and key could also be used with your load balancer to accept HTTPS traffic too. As mentioned earlier, this is really only suitable for internal environments where you can have your users manually trust the certificate.

Conclusion

Ditching the limitations of the Common Name field, self-signed certificates with Subject Alternative Name (SAN) extension enable you to secure multiple domains with ease. While self-signed certificates may not be suitable for public-facing websites, these certificates provide numerous benefits for internal environments or specific use cases. By using self-signed certificates with SAN in your ORDS instance, you can fortify your infrastructure security while efficiently managing multiple domains, all without breaking the bank.

How to check if ORDS is running

Oracle REST Data Services (ORDS) provides web services for an Oracle Database and allows for access to the database over the web. In a recent YouTube video I showed how to use ORDS in the new Oracle Developer DB Virtual Machine and briefly mentioned how to find the running ORDS process. Let’s go into that in more detail. In this article, we will discuss how to check if ORDS is running in a standalone ORDS deployments as well as deployments on Apache Tomcat and Oracle WebLogic Server.

  1. Checking ORDS on Standalone Deployments
  2. Checking ORDS on Apache Tomcat
  3. Checking ORDS on Oracle WebLogic Server
  4. What about Windows systems?
  5. Conclusion

Checking ORDS on Standalone Deployments

On a unix based system, the simplest way to check if ORDS is running is to use the jps command. This command will list all Java process that are currently running on the system. It is important to note that in order for jps to work, the JDK must be installed and the PATH environment variable must be set correctly. The jps command accepts a number of options and the most useful in this case are

  • -m to display the arguments passed to the main method
  • -l to display the full path name to the ords.war location. Pass that through a grep for ords to find the ords specific java process.
  • -v displays the arguments passed to the JVM.
jps -mlv | grep ords
8545 /home/oracle/ords/ords.war --config /home/oracle/ords_config serve --secure --port 443 -Doracle.dbtools.cmdline.home=/home/oracle/ords -Duser.language=en -Duser.region=US -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dnashorn.args=--no-deprecation-warning -Doracle.dbtools.cmdline.ShellCommand=ords -Duser.timezone=UTC

If ORDS is running in standalone mode, you should see a process with ords.war in the path. If this process is listed, then ORDS is running. Note that due to the -v option you also see the Java option oracle.dbtools.cmdline.home used. That should be the folder that the ords.war is found in and should also be the distribution directory. In the above example, the distribution directory is /home/oracle/ords/ and the ORDS command used to start ORDS was actually /home/oracle/ords/bin/ords --config /home/oracle/ords_config serve --secure --port 443

Another approach is to use the ps command. This command will list all processes currently running on the system. To check if ORDS is running, use the command ps -ef | grep ords.war. If you see a process with ords.war as the command, then ORDS is running. 

[oracle@localhost ~]$ ps -ef | grep ords.war
oracle      8545    8516  2 21:13 pts/1    00:00:49 /home/oracle/java/jdk-11.0.17/bin/java -Doracle.dbtools.cmdline.home=/home/oracle/ords -Duser.language=en -Duser.region=US -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dnashorn.args=--no-deprecation-warning -Doracle.dbtools.cmdline.ShellCommand=ords -Duser.timezone=UTC -jar /home/oracle/ords/ords.war --config /home/oracle/ords_config serve --secure --port 443
oracle      9554    3521  0 21:42 pts/0    00:00:00 grep --color=auto ords.war

You’ll also see similar information as with the jps command but also the java executable used at start up too. Note that access to run ps is not always guaranteed and it main not be available for the user you are logged in as.

One note about the command line arguments one can see for the running Java processes. It can be seen by other users. This is one of the reasons that ORDS does not accept a password as a command line option. That password would be visible to anyone able to list the running processes. Either through jps or ps.

Checking ORDS on Apache Tomcat

If it’s enabled, use the Tomcat manager web application, or at the very least the catalina log files, to confirm that ORDS web application is deployed and started. If not, then jps on the command line is the next logical choice.

When ORDS is deployed on Apache Tomcat, you can use the jps command to check if the server is running and get further information about where the ords.war might be deployed. Run jps -mlv as before but this time grep for the catalina package.

jps -mlv | grep catalina
88 org.apache.catalina.startup.Bootstrap start --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED -Djava.util.logging.config.file=/usr/local/tomcat/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Dconfig.url=/u01/oracle/properties/config -Djdk.tls.ephemeralDHKeySize=2048 -Djava.protocol.handler.pkgs=org.apache.catalina.webresources -Dorg.apache.catalina.security.SecurityListener.UMASK=0027 -Dignore.endorsed.dirs= -Dcatalina.base=/usr/local/tomcat -Dcatalina.home=/usr/local/tomcat -Djava.io.tmpdir=/usr/local/tomcat/temp

The above indicates that catalina.base is /usr/local/tomcat and most people use the automatic web application deployment by placing the ords.war in the $CATALINA_BASE/webapps/ directory.

ls -la /usr/local/tomcat/webapps/
total 92384
drwxr-xr-x 1 root root       62 Apr 11 06:40 .
drwxr-xr-x 1 root root       77 Apr 11 06:40 ..
drwxr-x--- 5 root root       67 Apr 11 05:38 ords
-rw-r--r-- 1 root root 94599760 Apr 10 19:45 ords.war
drwxr-xr-x 3 root root       45 Apr 11 05:38 ROOT

That directory listing shows the ords.war file and that it has been exploded by Tomcat into the ords directory. It’s not a guarantee that ORDS was deployed successfully, one would have to check the Tomcat logs, but it is a good indicator.

Checking ORDS on Oracle WebLogic Server

If it’s enabled, use the WebLogic console or WLST to confirm that ORDS web application is deployed and started.

Similar to Apache Tomcat, the Oracle WebLogic Server is a Java application so yet again, it is the jps utility that is the starting point to get information on the server(s) running and their configuration.

jps -mvl | grep weblogic
80 weblogic.Server -Djava.security.egd=file:/dev/./urandom -Dlaunch.use.env.classpath=true -Dweblogic.Name=AdminServer -Djava.security.policy=/u01/oracle/wlserver/server/lib/weblogic.policy -Dconfig.url=/u01/oracle/properties/config -Djava.system.class.loader=com.oracle.classloader.weblogic.LaunchClassLoader -javaagent:/u01/oracle/wlserver/server/lib/debugpatch-agent.jar -da -Dwls.home=/u01/oracle/wlserver/server -Dweblogic.home=/u01/oracle/wlserver/server

The output indicates that the weblogic.home is /u01/oracle/wlserver/server. Unlike with Tomcat, one is not going to find a straight forward web application deployment directory under the weblogic.home. There’s a little more digging required to check if a server is configured to deploy ORDS and we’ll use the weblogic.Name parameter ( AdminServer in this case) to when digging deeper. The weblogic.home just indicates where the server java application is being executed from. The server runtime configuration is being picked up separately. In the majority of installations that will be in a related user_projects/domains directory found two levels up. For the above WLS instance that would be /u01/oracle/user_projects/domains/.

That directory may have the configuration for multiple domains but quite often there is just one: base_domain. From there you can get a little more information on how the server identified by the above weblogic.Name. The domain configuration is persisted in /u01/oracle/user_projects/domains/base_domain/config/config.xml and you can see there is an app-deployment configuration targetting the AdminServer.

<?xml version="1.0" encoding="UTF-8"?>
<domain xsi:schemaLocation="http://xmlns.oracle.com/weblogic/security/wls http://xmlns.oracle.com/weblogic/security/wls/1.0/wls.xsd http://xmlns.oracle.com/weblogic/domain http://xmlns.oracle.com/weblogic/1.0/domain.xsd http://xmlns.oracle.com/weblogic/security http://xmlns.oracle.com/weblogic/1.0/security.xsd http://xmlns.oracle.com/weblogic/security/xacml http://xmlns.oracle.com/weblogic/security/xacml/1.0/xacml.xsd" xmlns="http://xmlns.oracle.com/weblogic/domain" xmlns:sec="http://xmlns.oracle.com/weblogic/security" xmlns:wls="http://xmlns.oracle.com/weblogic/security/wls" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <name>base_domain</name>
  <domain-version>14.1.1.0.0</domain-version>
...
  <server>
    <name>AdminServer</name>
    <ssl>
      <name>AdminServer</name>
      <enabled>true</enabled>
    </ssl>
    <listen-address/>
  </server>
...
  <app-deployment>
    <name>ords</name>
    <target>AdminServer</target>
    <source-path>/u01/oracle/ords/ords.war</source-path>
    <staging-mode>nostage</staging-mode>
  </app-deployment>
...
</domain>

If you see this app-deployment configuration in place it is not a complete guarantee that ORDS successfully deployed when the server started but it is a good indication.

What about Windows systems?

The syntax for path separates might be different but the same jps utility options apply and the relative file locations will also be the same for standalone, Tomcat and WebLogic.

Conclusion

In summary, the jps utility, also known as the Java Virtual Machine Process Status Tool, that comes with your Java SE distribution is your friend. Just from the command line, it can guide you in discovering more about the ORDS instance running on your machine irrespective of deployment mode.