Follow the Coffee

Tag: ords standalone mode

  • ORDS Standalone: specifying a response header with jetty.xml

    NOTE: This article shows how to include a jetty.xml file in your ORDS Standalone deployment, so a user-defined response header is provided with each HTTP response. I'm also requesting that all or some of what you see below make it into our docs. The following article picks up from where this one left off.
    NOTE: A Load Balancer or Reverse Proxy can achieve this same result. If your current ORDS deployment consists of either, you may prefer to add header "rules" there instead.
    Should you choose to operate ORDS in Standalone mode, you can rely on the Jetty server to provide this header rule. See the this section of my latest article for configuring the /etc folder.

    Start here

    Once you have created the /etc folder, save the following code block as a XML file using an easily recognizable file name.

    We use jetty-response.xml in our example.
    <?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
  <Call name="insertHandler">
  <Arg>
    <New class="org.eclipse.jetty.rewrite.handler.RewriteHandler">
      <Get id="Rewrite" name="ruleContainer" />
      <Call name="addRule">
        <Arg>
          <New id="header"  class="org.eclipse.jetty.rewrite.handler.HeaderPatternRule">
            <Set name="pattern">*</Set>
            <Set name="name">Strict-Transport-Security</Set>
            <Set name="value">max-age=31536000;includeSubDomains</Set>
          </New>
        </Arg>
      </Call>
    </New>
  </Arg>
</Call>
</Configure>

    In this example, we use jetty-response.xml as the file name. With this file included in the /etc directory, ORDS will “pick up” this configuration setting during runtime.1

    Some details of this file

    This jetty-response.xml file will enable ORDS Standalone to include the Strict-Transport-Security header name and its values max-age=3153600;includeSubDomains in each response to a request.2 In lay terms this XML file establishes a new Jetty response header, named Strict-Transport-Security, it applies to its responses for all requests (denoted by the *), and this header’s value is comprised of the following:

    • max-age=31536000;
    • includeSubDomains

    To illustrate this behavior, consider the following curl command and subsequent response. A request is sent to a resource (in this case /departments_json) and the subsequent ORDS response includes:

    1. a JSON payload
    2. the typical/standard headers, and
    3. additional headers indicated in the jetty-response.xml file

    And that’s it, you’ve yet again customized the Jetty server (that is responsible for ORDS Standalone)!

    That’s it for now

    Similarly to the Jetty Access Log example, these XML files can be a quick and easy way to introduce additional functionality into your ORDS Stand-Alone deployment. What else can you imagine? Take a look at the Jetty APIs for inspiration. Did you know you can extend ORDS with plugins, too?

    And of course, obligatory ORDS resources: Download ORDS | Oracle ORDS forum | ORDS Docs | ORDS playlist

    Follow

    And don’t forget to follow, like, subscribe, share, taunt, troll, or stalk me!

    Footnotes

    1. What the hell is runtime? Having no formal education in software engineering, my understanding is that runtime has to do with the execution of a program. Runtime relates to the initial and continued execution of the program. In the case of these XML files, the instructions therein are not formally part of the Jetty server but are included in the instructions when you issue the ords serve command. Doing so effectively starts up the Jetty web server. Jetty then recognizes there are files in the /etc folder and includes them when it enters into “runtime” or the “runtime environment.” This Wikipedia post is a great place to start. But I certainly wouldn’t use that as the “official” definition. This stackoverflow thread is extremely helpful as well. ↩︎
    2. Strict-Transport-Security (about this header) is a response header. This header is used to inform the browser that HTTPS should only be used to access ORDS resource/s. You’ve probably seen * used in the ORDS documentation. In this case, <Set name="pattern">*</Set> found in the XML file is used * as a wildcard (i.e. I interpret this as “apply this rule to everything and anything.”). The <Set name="value">max-age=31536000;includeSubDomains</Set> line includes the “directives”: max-age=3153600; and includeSubDomains. Examples of subdomains would be something like: en.wikipedia.org, where en (English language) is a subdomain of wikipedia.org; more details here. ↩︎

  • ORDS Standalone access logs: Jetty and customizing with XML

    ORDS Standalone access logs: Jetty and customizing with XML

    Did you know that you can very quickly and easily enable access logging when you are running ORDS in standalone mode (i.e., when using the embedded Jetty server)?

    FYI: This article is an excerpt from a living document I've been working on dedicated to ORDS installation, configuration, and usage (from the development/developer's perspective). 

    And in true "me" fashion, I've sufficiently traveled down the rabbit hole and back for your benefit! What you'll see below is a proposed update to the related section of the current ORDS docs (specifically, 5.2.3 Using Jetty XML Configuration). Some of what you see here might not make it to the official docs, however, I do think there is some good background and references. In fact, some of the "examples" might not make it either 😢.

    Proposed/updated section

    NOTE: I intentionally made things redundant as possible. This way, when you are scanning a discrete section you should hopefully have enough context to accomplish what you want in as little time as possible.

    5.2.3 Using Jetty XML Configuration Files

    This section describes how to configure the ORDS Jetty server (i.e., Standalone mode) for additional functionality using Jetty XML configuration files.

    Some background

    When ORDS is in Standalone mode (i.e., relying on the embedded Jetty server as its web server), ORDS can detect and “pick up” user-provided configuration settings found in the [ORDS configuration directory]/global/standalone/etc directory.

    NOTE: You must create the [ORDS configuration directory]/global/standalone/etc directory. The /etc directory is not part of a standard ORDS configuration.
    FYI: If you are familiar with Jetty, then just know that the ORDS /etc. directory is analogous to the JETTY_BASE directory, found in a standard Jetty deployment.1

    5.2.3.1 Jetty Access Logs

    NOTE: Beginning with ORDS version 24.1, the standalone ORDS Access Log format was updated to include additional format codes.2
    ORDS versionsJetty Format codes usedAccess Log example
    23.4 and earlier“%h %l %u %t “%r” %s %b”127.0.0.1 – frank [10/Oct/2000:13:55:36 -0700] “GET /ords HTTP/1.1” 302
    24.1 and later“%{client}a %u %t “%r” %s %{CLF}O “%{Referrer}i” “%{User-Agent}i” %{ms}T %{Host}i”192.168.122.1 – [27/Mar/2023:23:00:07 +0000] “GET /ords/ HTTP/1.1” 302 – “-” “Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/111.0” 132 192.168.122.149:8080
    Comparing ORDS access log formats pre- and post-version 24.1.

    ORDS Standalone access logs will automatically be enabled once an access log location has been configured. You can enable Standalone logging by executing the following command:

    ords config set standalone.access.log [/Path to the access log location of your choosing]

    After issuing this configuration command, the ORDS CLI will echo back the location. You can review your configuration settings by executing the ords config list --include-defaults command.

    You will also see a new <entry></entry> has been saved to your /global/standalone/settings.xml file in your ORDS configuration folder.

    In most cases, the ORDS-provided Access Log data should be sufficient. However, should you choose to create your own custom access log, you may do so with Jetty XML files.3

    5.2.3.1.1 Jetty examples

    The behavior of the access log will differ depending on your configuration settings. Three possible scenarios for access logs are included.

    NOTE: The inclusion of these XML files at runtime changes Jetty server behavior and not ORDS behavior.
    Scenario 1: a jetty-access-log.xml file IS included and standalone.access.log location IS NOT set

    In this first scenario, you do not need to “set” the standalone.access.log location. As can be seen in the below image:

    You will, however, need to create an /etc directory in your ORDS configuration folder, similar to how you see below:

    [ORDS configuration directory]/global/standalone/etc

    An example:

    In the above image the /etc folder is nested under the /standalone folder, the /standalone folder is nested under the /global folder, and the /global folder is nested under the ORDS configuration folder (your unique configuration folder name and absolute folder paths will differ).

    Place the following jetty-access-log.xml4 file into that /etc folder.

    This jetty-access-log.xml file is comprised of the following properties:

    <?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
    <Ref id="Handlers">
      <Call name="addHandler">
        <Arg>
          <New id="RequestLog" class="org.eclipse.jetty.server.handler.RequestLogHandler">
            <Set name="requestLog">
              <New id="RequestLogImpl" class="org.eclipse.jetty.server.CustomRequestLog">
                <Arg>/Users/choina/ords_access_logs/access.log</Arg>
                <Arg>%{remote}a - %u %t "%r" %s %O "%{Referer}i" "%{User-Agent}i"</Arg>
              </New>
            </Set>
          </New>
        </Arg>
      </Call>
    </Ref>
</Configure>
    Notice the <Arg> tags.

    Pay special attention to the <Arg></Arg> tags. The first <Arg>ument informs Jetty where and how to save the access log file (i.e., save as access.log at the location indicated). The second argument specifies the format strings to include in the log file. For a detailed explanation of these format strings, see the Jetty Access Logs section of this document.

    NOTE: The format strings used in this sample XML file were chosen arbitrarily. You can include whatever relevant information, assuming it is available. See here for details.

    Once you have saved this file, you may then start ORDS normally (i.e., with the ords serve command). ORDS will then save and append Jetty (Standalone) access log information to the access.log file. You can later view the results and formatting of this log at the location you specified:

    An example access log file.
    Reviewing the contents of the access log file.
    NOTE: You can remove this file from your ORDS configuration prior to the next time ORDS is started, and it will have no impact on your service.
    Scenario 2: A jetty-access-log.xml file IS included and standalone.access.log location IS set

    In this scenario, you will have already completed the following two steps:

    1. Configured the standalone.access.log setting using the ORDS CLI, and
    2. You have included a jetty-access-log.xml file (or whatever file name of your choosing) in the /etc folder.
    Configuring standalone.access.log

    Verifying the configuration setting with the ords config list --include-defaults command.
    NOTE: You will also see a new <entry></entry> has been saved to your /global/standalone/settings.xml file in your ORDS configuration folder.

    After executing the ords serve command, you’ll also see the standalone.access.log configuration setting included as ORDS initializes.

    You’ll also notice two versions of the access log files in the /[access log] folder location.

    One file for the access.log, which was created from the jetty-access-log.xml file you included.

    The other will be a log file with the format of: ords_[log file date].log.

    This second file5 (and subsequent log files saved by date), is the one that is automatically created for you as a result of setting the standalone.access.log property in your ORDS configuration.

    Scenario 3: A jetty-access-log.xml file IS NOT included and standalone.access.log location IS set

    This is effectively the standard, typical way you would configure ORDS for Standalone access logging.

    Set the standalone.access.log configuration setting with the following command:

    ords config set standalone.access.log [/Path to the access log location of your choosing]
    NOTE: You will also see a new <entry></entry> has been saved to your /global/standalone/settings.xml file in your ORDS configuration folder.

    Remove any [jetty].xml files from your /etc folder.

    Once you start ORDS (i.e., ords serve) you’ll find access logs in your access log folder. These and subsequent logs will be saved in the ords_[log file date].log format.

    And that’s it! You made it 😃.

    And some considerations

    The third scenario (the standard option) seems to be the most logical and convenient method for saving Standalone access logs, for a few reasons:

    • No need to rely on XML files
    • Log files are conveniently saved with an intuitive naming convention, and
    • Log files are saved in a recognized format; making it easier for third-party logging analytics tools to ingest the data

    Footnotes are below. If you thought this was helpful, please share and comment! That’s all for now 😬.

    Follow

    And don’t forget to follow, like, subscribe, share, taunt, troll, or stalk me!

    Footnotes

    1. It’s not crucial for you to have a deep understanding of how Jetty works. At a basic level, just know that there will always be a JETTY_BASE as well as a JETTY_HOME directory. And, in a standard Jetty installation, JETTY_BASE is where your modules and any customization live. While JETTY_HOME is where the Jetty binaries live. For the purposes of ORDS, the [ORDS configuration directory]/global/standalone/etc directory can be looked at as your JETTY_BASE. That is where you’ll place JETTY.XML files; similar to the ones you’ll see in this section’s examples. Again, none of this is important for you to know unless, of course, you’d like to learn more about Jetty. ↩︎
    2. About Jetty Custom Request Log format codes and syntax ↩︎
    3. Jetty XML files can be viewed as a simpler way to add additional configuration settings to your Jetty server without having to create a custom Jetty Module. For a deeper dive into Jetty modules, how to configure them, and customizations see here. ↩︎
    4. This file can be named [anything].xml. The format, contents, and arguments therein are what are important. ↩︎
    5. The ORDS-provided access logs, automatically save in the NCSA Common log format. Since other logging applications and tools may expect to ingest logs in this format, it might be worth considering whether or not you actually want to customize your own Jetty access logs. You can find details on the NCSA Common log format here or visit the now-archived HTTPd page for more information on the creation of this format. ↩︎