DBA Hub

📋Steps in this guide1/9

Oracle REST Data Services (ORDS) : Standalone Mode (ORDS Version 22.1 Onward)

This article provides an overview of using Oracle REST Data Services (ORDS) version 22.1 onward in standalone mode.

oracle miscconfigurationintermediate
by OracleDba
16 views
1

Installation

We will use the following environment variables when referencing the paths in this article. Notice we are adding the directory to our , so we don't have to explicitly state the path each time we use the command. Setting the environment variable means we don't need to explicitly use the argument in the commands below, but we will still include it anyway. The default Java heap size will result in failures, so we need to set the heap size using the environment variable. We can then use the command to start ORDS in standalone mode. Resources will now be available from the following URL, adjusting your hostname as applicable. Standalone mode will capture the console and push all log information to it. We can stop ORDS using CTRL+C. For a production deployment we should start ORDS as a background process and push the output to a log file. For example, we could create a file called "~/scripts/start_ords.sh" with the following contents. Remember to adjust paths as required. We can kill ORDS by killing the background process. We create a scripts called "~/scripts/stop_ords.sh" with the following contents. We create the log directory and make the scripts executable. We can then easily stop and start ORDS using the scripts. By default ORDS uses HTTP on port 8080. We can alter the port using the argument. We can make ORDS use HTTPS by adding the argument, which will default the port to 8443, but we can alter that using the argument. In this example we explicitly set the port to the default HTTPS value. ORDS will automatically create a self-signed certificate for use with SSL if you don't specify a valid certificate and key. The certificate and key are stored in the "$ORDS_CONFIG/global/standalone" directory. Resources will now be available from the following URL, adjusting your hostname as applicable. We can set this as the default action using the following command. The presence of the HTTPS port implies ORDS is running in secure mode. The settings are added to the "$ORDS_CONFIG/global/settings.xml" file. We can now run ORDS using HTTPS with the following command. If you are using the command line arguments, remember to amend your "start_ords.sh" script. You should probably be fronting ORDS with a reverse proxy or a load balancer, which is where your Certificate Authority (CA) certificates should live. Even so, you will probably want your internal traffic to use HTTPS also, so you will need to configure Jetty to use HTTPS. If you have a proper CA certificate and key, make sure they are in DER format. In this case we will manually create a new self-signed certificate and use that for the HTTPS configuration. Remember to adjust the "dname" and passwords as required. If everything has gone OK you now have key and certificate in DER format. That file names are based on your hostname, so they will probably look different. We can now start ORDS using this certificate and key as follows. The and settings are implied because we are using a certificate, but we could set them explicitly and get the same result. Resources will now be available from the following URL, adjusting your hostname as applicable. We can set this as the default using the following commands. The presence of the HTTPS port implies ORDS is running in secure mode. The settings are added to the "$ORDS_CONFIG/global/settings.xml" file. We can now run ORDS using HTTPS and our certificate with the following command. If you are using the command line arguments, remember to amend your "start_ords.sh" script. When using ORDS to front APEX applications, ORDS should be configured to serve the APEX static files. The settings are added to the "$ORDS_CONFIG/global/settings.xml" file. We must restart ORDS for the changes to take effect. ORDS can be used to serve static content like a regular web server. The default location requires the following path. The default location can be altered using the argument on the command line, or by amending the following default setting. If you have altered the default setting, ORDS will need to be restarted for it to take effect. ORDS will automatically handle the typical HTTP errors. If you are fronting ORDS with a load balancer, you may wish to use that to handle custom error messages, rather than altering the ORDS configuration. If you need it, ORDS can handle custom error pages. Amend the setting with the location of your custom error pages. Create the required custom error files. I've just created some simple ones to test with. Restart ORDS. Access logs are really important if you want to know who is accessing your web server. We use the setting to determine where ORDS writes the access logs. Restart ORDS for the setting to take effect. Once we access ORDS we will see an access log created in the directory we specified. The access logs have the "ords_YYYY_MM_DD.log" name format. The full list of settings can be displayed using the following command. For more information see: - Serve Commands for Running in Standalone Mode - Oracle REST Data Services (ORDS) : All Articles - Oracle REST Data Services (ORDS) : Installation on Tomcat (ORDS Version 22.1 Onward) Hope this helps. Regards Tim...

Code/Command (click line numbers to comment):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
export JAVA_HOME=/u01/java/latest
export ORDS_HOME=/u01/ords
export ORDS_CONFIG=/u01/config/ords
export PATH=${ORDS_HOME}/bin:${PATH}

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve

http://localhost:8080/ords/

#!/bin/bash
export PATH=/usr/sbin:/usr/local/bin:/usr/bin:/usr/local/sbin:$PATH
export JAVA_HOME=/u01/java/latest
export ORDS_HOME=/u01/ords
export ORDS_CONFIG=/u01/config/ords
LOGFILE=/home/oracle/scripts/logs/ords-`date +"%Y""%m""%d"`.log
export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"
nohup ${ORDS_HOME}/bin/ords --config ${ORDS_CONFIG} serve >> $LOGFILE 2>&1 &
echo "View log file with : tail -f $LOGFILE"

#!/bin/bash
export PATH=/usr/sbin:/usr/local/bin:/usr/bin:/usr/local/sbin:$PATH
kill `ps -ef | grep [o]rds.war | awk '{print $2}'`

mkdir -p ~/scripts/logs
chmod u+x ~/scripts/*.sh

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --secure --port 8443

https://localhost:8443/ords/

ords --config ${ORDS_CONFIG} config set standalone.https.port 8443

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve

mkdir ~/keystore
cd ~/keystore

# Create a self-signed certificate in a JKS keystore.
$JAVA_HOME/bin/keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks \
   -dname "CN=`hostname`, OU=Example Department, O=Example Company, L=Birmingham, ST=West Midlands, C=GB" \
   -storepass password1 -validity 3600 -keysize 2048 -keypass password1

# Create a PKCS12 keystore from the JKS keystore.
$JAVA_HOME/bin/keytool -importkeystore -srckeystore keystore.jks -srcalias selfsigned -srcstorepass password1 \
   -destkeystore keystore.p12 -deststoretype PKCS12 -deststorepass password1 -destkeypass password1 

# Extract the key and certificate in PEM format.
openssl pkcs12 -in keystore.p12 -nodes -nocerts -out `hostname`-key.pem
openssl pkcs12 -in keystore.p12 -nokeys -out `hostname`.pem

# Convert them to DER format.
openssl pkcs8 -topk8 -inform PEM -outform DER -in `hostname`-key.pem -out `hostname`-key.der -nocrypt
openssl x509 -inform PEM -outform DER -in `hostname`.pem -out `hostname`.der

$ ls *.der
localhost.localdomain.der  localhost.localdomain-key.der
$

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --certificate ~/keystore/localhost.localdomain.der --key ~/keystore/localhost.localdomain-key.der

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --secure --port 8443 --certificate ~/keystore/localhost.localdomain.der --key ~/keystore/localhost.localdomain-key.der

https://localhost:8443/ords/

ords --config ${ORDS_CONFIG} config set standalone.https.port 8443
ords --config ${ORDS_CONFIG} config set standalone.https.cert ~/keystore/localhost.localdomain.der
ords --config ${ORDS_CONFIG} config set standalone.https.cert.key ~/keystore/localhost.localdomain-key.der

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve

export APEX_IMAGES=/u01/software/apex/images

ords --config ${ORDS_CONFIG} config set standalone.static.path ${APEX_IMAGES}

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

mkdir -p ${ORDS_CONFIG}/global/doc_root

ords --config ${ORDS_CONFIG} config set standalone.doc.root ${ORDS_CONFIG}/global/doc_root

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

ords --config ${ORDS_CONFIG} config set error.externalPath ~/error-pages

mkdir -p ~/error-pages
echo "404 Error: Whoops" > ~/error-pages/404.html
echo "500 Error: Whoops" > ~/error-pages/500.html

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

ords --config ${ORDS_CONFIG} config set standalone.access.log ${ORDS_CONFIG}/logs

~/scripts/stop_ords.sh
~/scripts/start_ords.sh

$
ords config info
ORDS: Release 22.1 Production on Fri Apr 22 10:16:02 2022

Copyright (c) 2010, 2022, Oracle.

Configuration:
  /u01/config/ords/

Settings:

apex.security.administrator.rolesComma de-limited list of
                                 additional roles to assign
                                 authenticated APEX
                                 administrator type users.

apex.security.developer.roles    Comma de-limited list of
                                 additional roles to assign
                                 authenticated APEX developer
                                 type users.

apex.security.user.roles         Comma de-limited list of
                                 additional roles to assign
                                 authenticated regular APEX
                                 users.

autoupgrade.api.aulocation       A configuration setting for
                                 AutoUpgrade.jar location.

autoupgrade.api.enabled          A configuration setting to
                                 enable AutoUpgrade REST API
                                 features.

autoupgrade.api.jvmlocation      A configuration setting for
                                 AutoUpgrade REST API JVM
                                 location.

autoupgrade.api.loglocation      A configuration setting for
                                 AutoUpgrade REST API log
                                 location.

cache.metadata.enabled           Specifies the setting to
                                 enable or disable metadata
                                 caching.

cache.metadata.timeout           Specifies the setting to
                                 determine for how long a
                                 metadata record remains in
                                 the cache. Longer duration
                                 means, it takes longer to
                                 view the applied changes. The
                                 formats accepted are based on
                                 the ISO-8601 duration format.

database.api.enabled             Enable Database API feature.

database.api.management.services.disabledDisable the Database API
                                 administration related
                                 services. Only applicable
                                 when Database API is enabled.

db.adminUser                     The username for the database
                                 account that ORDS will use
                                 for administration operations
                                 in the database.

db.adminUser.password            The password for the database
                                 account that ORDS will use
                                 for administration operations
                                 in the database.

db.cdb.adminUser                 The username for the database
                                 account that ORDS will use
                                 for Pluggable Database
                                 Lifecycle Management.

db.cdb.adminUser.password        The password for the database
                                 account that ORDS will use
                                 for Pluggable Database
                                 Lifecycle Management.

db.connectionType                The database connection type.
                                 Specify one of the values:
                                 basic, tns, customurl.

db.credentialsSource             Specifies the source for
                                 database credentials when
                                 creating a direct connection
                                 for running SQL statements.
                                 Value can be one of: pool or
                                 request. If pool is used, the
                                 credentials defined in this
                                 pool will be used to create a
                                 JDBC connection. If request
                                 is used, the credentials in
                                 the request will be used to
                                 create a JDBC connection and
                                 if successful grant the
                                 requestor SQL Developer role.
                                 The default value is pool.

db.customURL                     The JDBC URL connection to
                                 connect to the database.

db.hostname                      The host name of the database
                                 server.

db.invalidPoolTimeout            Specifies how long to wait
                                 before retrying an invalid
                                 pool.

db.password                      The database password.

db.poolDestroyTimeout            Indicates how long to wait to
                                 gracefully destroy a pool,
                                 before moving to forcefully
                                 destroy all connections
                                 including borrowed ones.

db.port                          The port of the database
                                 server listener.

db.serviceNameSuffix             The service name suffix for
                                 PDBs connected to the CDB.

db.servicename                   The database service name.

db.tnsAliasName                  The TNS alias name that
                                 matches the name in the
                                 tnsnames.ora file.

db.tnsDirectory                  The directory location of
                                 your tnsnames.ora file.

db.username                      The database user name.

db.wallet.zip                    The wallet archive (provided
                                 in BASE64 encoding)
                                 containing connection details
                                 for the pool.

db.wallet.zip.path               The path to a wallet archive
                                 containing connection details
                                 for the pool.

db.wallet.zip.service            Specifies the service name in
                                 the wallet archive for the
                                 pool.

debug.printDebugToScreen         Specifies whether to display
                                 error messages in the browser.

debug.trackResources             Enable tracking of JDBC
                                 resources that if not
                                 released will cause resource
                                 leaks/exhaustion in the
                                 database. Tracking imposes a
                                 performance overhead.

error.externalPath               The path to the external
                                 error pages.

error.responseFormat             Specifies in what format
                                 error responses should be
                                 rendered. Possible values:
                                 HTTP, JSON, AUTO. Defaults to
                                 AUTO.

feature.openservicebroker.excludeTo disable the Open Service
                                 Broker services available for
                                 the pool.

feature.sdw                      Enable Database Actions
                                 feature.

http.cookie.filter               A comma separated list of
                                 HTTP Cookies to exclude when
                                 initializing an Oracle Web
                                 Agent environment.

icap.port                        Specifies the Internet
                                 Content Adaptation Protocol
                                 (ICAP) port to virus scan
                                 files. Either icap.port or
                                 icap.secure.port are required
                                 to have a value when
                                 icap.server is set.

icap.secure.port                 Specifies the Internet
                                 Content Adaptation Protocol
                                 (ICAP) secure port to virus
                                 scan files. Either icap.port
                                 or icap.secure.port are
                                 required to have a value when
                                 icap.server is set.

icap.server                      Specifies the Internet
                                 Content Adaptation Protocol
                                 (ICAP) server name or IP
                                 address to virus scan files.

jdbc.DriverType                  The Oracle JDBC URL subtype
                                 that can have one of the
                                 values: thin, oci8. Defaults
                                 to thin.

jdbc.InactivityTimeout           Specify how long an available
                                 connection can remain idle
                                 before it is closed. The
                                 inactivity connection timeout
                                 is in seconds. Defaults to
                                 1800.

jdbc.InitialLimit                The initial size for the
                                 number of connections that
                                 will be created. Defaults to
                                 10.

jdbc.MaxConnectionReuseCount     Specify the maximum number of
                                 times to reuse a connection
                                 before it is discarded and
                                 replaced with a new
                                 connection.

jdbc.MaxLimit                    The maximum number of
                                 connections. Defaults to 10.

jdbc.MaxStatementsLimit          The maximum number of
                                 statements to cache for each
                                 connection. Defaults to 10.

jdbc.MinLimit                    The minimum number of
                                 connections. Defaults to 2.

jdbc.auth.admin.role             Identifies the database role
                                 that signifies the database
                                 user should get the SQL
                                 Administrator role.

jdbc.auth.enabled                Specifies if the PL/SQL
                                 Gateway calls can be
                                 authenticated using database
                                 users. Defaults to false. Set
                                 to true to enable feature.
                                 Oracle recommends not to use
                                 this feature. This feature
                                 used only to facilitate
                                 customers migrating from
                                 mod_plsql.

jdbc.cleanup.mode                Specifies how a pooled JDBC
                                 connection, and corresponding
                                 database session, is released
                                 when a request has been
                                 processed.

jdbc.driverName                  The name of the JDBC driver
                                 to use.

jdbc.statementTimeout            Specify how long a borrowed
                                 (in use) connection can
                                 remain unused before it is
                                 considered as abandoned and
                                 reclaimed. The abandoned
                                 connection timeout is in
                                 seconds.

json.sdo.geometry.output.geojson Specify that SDO Geometry
                                 data should be returned in
                                 GeoJSON format.

misc.defaultPage                 Default page (PL/SQL
                                 procedure) to invoke if the
                                 URL points to the context
                                 root of a database pool.
                                 Default value is apex.

misc.pagination.maxRows          Specifies the maximum number
                                 of rows that will be returned
                                 from a query when processing
                                 a RESTful service and that
                                 will be returned from a
                                 nested cursor in a result
                                 set. Affects all RESTful
                                 services generated through a
                                 SQL query, regardless of
                                 whether the resource is
                                 paginated. Defaults to 10000.

owa.trace.sql                    Boolean property that if true
                                 causes a trace of the SQL
                                 statements performed by
                                 Oracle Web Agent to be echoed
                                 to the log.

plsql.gateway.mode               Indicates if the PL/SQL
                                 Gateway functionality should
                                 be available for a pool or
                                 not. Value can be one of:
                                 disabled, direct or proxied.
                                 If direct is used, the pool
                                 will serve PL/SQL Gateway
                                 requests directly. If proxied
                                 is used, PLSQL_GATEWAY_CONFIG
                                 view is used to determine the
                                 user to proxy to.

procedure.rest.preHook           Name of a stored PL/SQL
                                 function that should be
                                 invoked prior to dispatching
                                 any REST request.

request.traceHeaderName          Denotes the name of the HTTP
                                 request header that uniquely
                                 identifies the request end to
                                 end as it passes through the
                                 various layers of the
                                 application stack. In Oracle
                                 this header is commonly
                                 referred to as the ECID
                                 (Entity Context ID).

resource.templates.enabled       Deprecated. Configuration
                                 property indicating if the
                                 legacy resource templates
                                 (APEX based REST) should be
                                 enabled or not. False by
                                 default. The
                                 resource-templates code base
                                 is not compatible with the
                                 single pool
                                 (ORDS_PUBLIC_USER)
                                 architecture so must be
                                 disabled.

restEnabledSql.active            Enable REST-Enabled SQL
                                 feature.

security.credentials.attempts    The maximum number of
                                 unsuccessful password
                                 attempts allowed. Enabled by
                                 setting a positive integer
                                 value. Defaults to -1.

security.credentials.file        The file where credentials
                                 are stored.

security.credentials.lock.time   The period to lock account
                                 that has exceeded maximum
                                 attempts. Defaults to 10
                                 minutes.

security.requestValidationFunctionSpecifies a validation
                                 function to determine if the
                                 requested procedure in the
                                 URL should be allowed or
                                 disallowed for processing.
                                 The function should return
                                 true if the procedure is
                                 allowed; otherwise, return
                                 false.

security.validationFunctionType  Indicate what type the
                                 security.requestValidationFunc
                                 ion is: javascript or plsql.
                                 Defaults to plsql.

security.verifySSL               Indicate whether HTTPS is
                                 available in your environment.

standalone.access.log            Path to the folder to store
                                 HTTP request access logs. If
                                 not specified then no access
                                 log will be generated.

standalone.binds                 Comma separated list of host
                                 names or IP addresses to
                                 identify a specific network
                                 interface on which to listen,
                                 default 0.0.0.0.

standalone.context.path          The context path where {0} is
                                 located, defaults to /ords

standalone.doc.root              Points to the location where
                                 static resources, to be
                                 served under the / root
                                 server path are located.

standalone.http.port             HTTP listen port, default 8080

standalone.https.cert            SSL certificate path. If you
                                 are providing the SSL
                                 certificate, you must specify
                                 the certificate location.

standalone.https.cert.key        SSL certificate key path. If
                                 you are providing the SSL
                                 certificate, you must specify
                                 the certificate key location.

standalone.https.host            SSL certificate hostname

standalone.https.port            HTTPS listen port, default
                                 8443

standalone.static.context.path   The Context path where
                                 Application Express static
                                 resources are located,
                                 defaults to /i

standalone.static.path           Path to the folder containing
                                 static resources required by
                                 APEX

standalone.stop.timeout          The period for Standalone
                                 Mode to wait to gracefully
                                 shutdown.
$
2

Starting/Stopping ORDS in Standalone Mode

The default Java heap size will result in failures, so we need to set the heap size using the environment variable. We can then use the command to start ORDS in standalone mode. Resources will now be available from the following URL, adjusting your hostname as applicable. Standalone mode will capture the console and push all log information to it. We can stop ORDS using CTRL+C. For a production deployment we should start ORDS as a background process and push the output to a log file. For example, we could create a file called "~/scripts/start_ords.sh" with the following contents. Remember to adjust paths as required. We can kill ORDS by killing the background process. We create a scripts called "~/scripts/stop_ords.sh" with the following contents. We create the log directory and make the scripts executable. We can then easily stop and start ORDS using the scripts.

Code/Command (click line numbers to comment):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve

http://localhost:8080/ords/

#!/bin/bash
export PATH=/usr/sbin:/usr/local/bin:/usr/bin:/usr/local/sbin:$PATH
export JAVA_HOME=/u01/java/latest
export ORDS_HOME=/u01/ords
export ORDS_CONFIG=/u01/config/ords
LOGFILE=/home/oracle/scripts/logs/ords-`date +"%Y""%m""%d"`.log
export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"
nohup ${ORDS_HOME}/bin/ords --config ${ORDS_CONFIG} serve >> $LOGFILE 2>&1 &
echo "View log file with : tail -f $LOGFILE"

#!/bin/bash
export PATH=/usr/sbin:/usr/local/bin:/usr/bin:/usr/local/sbin:$PATH
kill `ps -ef | grep [o]rds.war | awk '{print $2}'`

mkdir -p ~/scripts/logs
chmod u+x ~/scripts/*.sh

~/scripts/stop_ords.sh
~/scripts/start_ords.sh
3

Auto SSL (HTTPS)

By default ORDS uses HTTP on port 8080. We can alter the port using the argument. We can make ORDS use HTTPS by adding the argument, which will default the port to 8443, but we can alter that using the argument. In this example we explicitly set the port to the default HTTPS value. ORDS will automatically create a self-signed certificate for use with SSL if you don't specify a valid certificate and key. The certificate and key are stored in the "$ORDS_CONFIG/global/standalone" directory. Resources will now be available from the following URL, adjusting your hostname as applicable. We can set this as the default action using the following command. The presence of the HTTPS port implies ORDS is running in secure mode. The settings are added to the "$ORDS_CONFIG/global/settings.xml" file. We can now run ORDS using HTTPS with the following command. If you are using the command line arguments, remember to amend your "start_ords.sh" script.

Code/Command (click line numbers to comment):

1
2
3
4
5
6
7
8
9
10
11
export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --secure --port 8443

https://localhost:8443/ords/

ords --config ${ORDS_CONFIG} config set standalone.https.port 8443

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve
4

SSL Configuration (HTTPS)

You should probably be fronting ORDS with a reverse proxy or a load balancer, which is where your Certificate Authority (CA) certificates should live. Even so, you will probably want your internal traffic to use HTTPS also, so you will need to configure Jetty to use HTTPS. If you have a proper CA certificate and key, make sure they are in DER format. In this case we will manually create a new self-signed certificate and use that for the HTTPS configuration. Remember to adjust the "dname" and passwords as required. If everything has gone OK you now have key and certificate in DER format. That file names are based on your hostname, so they will probably look different. We can now start ORDS using this certificate and key as follows. The and settings are implied because we are using a certificate, but we could set them explicitly and get the same result. Resources will now be available from the following URL, adjusting your hostname as applicable. We can set this as the default using the following commands. The presence of the HTTPS port implies ORDS is running in secure mode. The settings are added to the "$ORDS_CONFIG/global/settings.xml" file. We can now run ORDS using HTTPS and our certificate with the following command. If you are using the command line arguments, remember to amend your "start_ords.sh" script.

Code/Command (click line numbers to comment):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
mkdir ~/keystore
cd ~/keystore

# Create a self-signed certificate in a JKS keystore.
$JAVA_HOME/bin/keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks \
   -dname "CN=`hostname`, OU=Example Department, O=Example Company, L=Birmingham, ST=West Midlands, C=GB" \
   -storepass password1 -validity 3600 -keysize 2048 -keypass password1

# Create a PKCS12 keystore from the JKS keystore.
$JAVA_HOME/bin/keytool -importkeystore -srckeystore keystore.jks -srcalias selfsigned -srcstorepass password1 \
   -destkeystore keystore.p12 -deststoretype PKCS12 -deststorepass password1 -destkeypass password1 

# Extract the key and certificate in PEM format.
openssl pkcs12 -in keystore.p12 -nodes -nocerts -out `hostname`-key.pem
openssl pkcs12 -in keystore.p12 -nokeys -out `hostname`.pem

# Convert them to DER format.
openssl pkcs8 -topk8 -inform PEM -outform DER -in `hostname`-key.pem -out `hostname`-key.der -nocrypt
openssl x509 -inform PEM -outform DER -in `hostname`.pem -out `hostname`.der

$ ls *.der
localhost.localdomain.der  localhost.localdomain-key.der
$

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --certificate ~/keystore/localhost.localdomain.der --key ~/keystore/localhost.localdomain-key.der

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve --secure --port 8443 --certificate ~/keystore/localhost.localdomain.der --key ~/keystore/localhost.localdomain-key.der

https://localhost:8443/ords/

ords --config ${ORDS_CONFIG} config set standalone.https.port 8443
ords --config ${ORDS_CONFIG} config set standalone.https.cert ~/keystore/localhost.localdomain.der
ords --config ${ORDS_CONFIG} config set standalone.https.cert.key ~/keystore/localhost.localdomain-key.der

export _JAVA_OPTIONS="-Xms1126M -Xmx1126M"

ords --config ${ORDS_CONFIG} serve
5

APEX Static Images

When using ORDS to front APEX applications, ORDS should be configured to serve the APEX static files. The settings are added to the "$ORDS_CONFIG/global/settings.xml" file. We must restart ORDS for the changes to take effect.

Code/Command (click line numbers to comment):

1
2
3
4
5
6
export APEX_IMAGES=/u01/software/apex/images

ords --config ${ORDS_CONFIG} config set standalone.static.path ${APEX_IMAGES}

~/scripts/stop_ords.sh
~/scripts/start_ords.sh
6

Static Resources (Document Root)

ORDS can be used to serve static content like a regular web server. The default location requires the following path. The default location can be altered using the argument on the command line, or by amending the following default setting. If you have altered the default setting, ORDS will need to be restarted for it to take effect.

Code/Command (click line numbers to comment):

1
2
3
4
5
6
mkdir -p ${ORDS_CONFIG}/global/doc_root

ords --config ${ORDS_CONFIG} config set standalone.doc.root ${ORDS_CONFIG}/global/doc_root

~/scripts/stop_ords.sh
~/scripts/start_ords.sh
7

Custom Error Pages

ORDS will automatically handle the typical HTTP errors. If you are fronting ORDS with a load balancer, you may wish to use that to handle custom error messages, rather than altering the ORDS configuration. If you need it, ORDS can handle custom error pages. Amend the setting with the location of your custom error pages. Create the required custom error files. I've just created some simple ones to test with. Restart ORDS.

Code/Command (click line numbers to comment):

1
2
3
4
5
6
7
8
ords --config ${ORDS_CONFIG} config set error.externalPath ~/error-pages

mkdir -p ~/error-pages
echo "404 Error: Whoops" > ~/error-pages/404.html
echo "500 Error: Whoops" > ~/error-pages/500.html

~/scripts/stop_ords.sh
~/scripts/start_ords.sh
8

Access Log

Access logs are really important if you want to know who is accessing your web server. We use the setting to determine where ORDS writes the access logs. Restart ORDS for the setting to take effect. Once we access ORDS we will see an access log created in the directory we specified. The access logs have the "ords_YYYY_MM_DD.log" name format.

Code/Command (click line numbers to comment):

1
2
3
4
ords --config ${ORDS_CONFIG} config set standalone.access.log ${ORDS_CONFIG}/logs

~/scripts/stop_ords.sh
~/scripts/start_ords.sh
9

All Settings

The full list of settings can be displayed using the following command. For more information see: - Serve Commands for Running in Standalone Mode - Oracle REST Data Services (ORDS) : All Articles - Oracle REST Data Services (ORDS) : Installation on Tomcat (ORDS Version 22.1 Onward) Hope this helps. Regards Tim...

Code/Command (click line numbers to comment):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
$
ords config info
ORDS: Release 22.1 Production on Fri Apr 22 10:16:02 2022

Copyright (c) 2010, 2022, Oracle.

Configuration:
  /u01/config/ords/

Settings:

apex.security.administrator.rolesComma de-limited list of
                                 additional roles to assign
                                 authenticated APEX
                                 administrator type users.

apex.security.developer.roles    Comma de-limited list of
                                 additional roles to assign
                                 authenticated APEX developer
                                 type users.

apex.security.user.roles         Comma de-limited list of
                                 additional roles to assign
                                 authenticated regular APEX
                                 users.

autoupgrade.api.aulocation       A configuration setting for
                                 AutoUpgrade.jar location.

autoupgrade.api.enabled          A configuration setting to
                                 enable AutoUpgrade REST API
                                 features.

autoupgrade.api.jvmlocation      A configuration setting for
                                 AutoUpgrade REST API JVM
                                 location.

autoupgrade.api.loglocation      A configuration setting for
                                 AutoUpgrade REST API log
                                 location.

cache.metadata.enabled           Specifies the setting to
                                 enable or disable metadata
                                 caching.

cache.metadata.timeout           Specifies the setting to
                                 determine for how long a
                                 metadata record remains in
                                 the cache. Longer duration
                                 means, it takes longer to
                                 view the applied changes. The
                                 formats accepted are based on
                                 the ISO-8601 duration format.

database.api.enabled             Enable Database API feature.

database.api.management.services.disabledDisable the Database API
                                 administration related
                                 services. Only applicable
                                 when Database API is enabled.

db.adminUser                     The username for the database
                                 account that ORDS will use
                                 for administration operations
                                 in the database.

db.adminUser.password            The password for the database
                                 account that ORDS will use
                                 for administration operations
                                 in the database.

db.cdb.adminUser                 The username for the database
                                 account that ORDS will use
                                 for Pluggable Database
                                 Lifecycle Management.

db.cdb.adminUser.password        The password for the database
                                 account that ORDS will use
                                 for Pluggable Database
                                 Lifecycle Management.

db.connectionType                The database connection type.
                                 Specify one of the values:
                                 basic, tns, customurl.

db.credentialsSource             Specifies the source for
                                 database credentials when
                                 creating a direct connection
                                 for running SQL statements.
                                 Value can be one of: pool or
                                 request. If pool is used, the
                                 credentials defined in this
                                 pool will be used to create a
                                 JDBC connection. If request
                                 is used, the credentials in
                                 the request will be used to
                                 create a JDBC connection and
                                 if successful grant the
                                 requestor SQL Developer role.
                                 The default value is pool.

db.customURL                     The JDBC URL connection to
                                 connect to the database.

db.hostname                      The host name of the database
                                 server.

db.invalidPoolTimeout            Specifies how long to wait
                                 before retrying an invalid
                                 pool.

db.password                      The database password.

db.poolDestroyTimeout            Indicates how long to wait to
                                 gracefully destroy a pool,
                                 before moving to forcefully
                                 destroy all connections
                                 including borrowed ones.

db.port                          The port of the database
                                 server listener.

db.serviceNameSuffix             The service name suffix for
                                 PDBs connected to the CDB.

db.servicename                   The database service name.

db.tnsAliasName                  The TNS alias name that
                                 matches the name in the
                                 tnsnames.ora file.

db.tnsDirectory                  The directory location of
                                 your tnsnames.ora file.

db.username                      The database user name.

db.wallet.zip                    The wallet archive (provided
                                 in BASE64 encoding)
                                 containing connection details
                                 for the pool.

db.wallet.zip.path               The path to a wallet archive
                                 containing connection details
                                 for the pool.

db.wallet.zip.service            Specifies the service name in
                                 the wallet archive for the
                                 pool.

debug.printDebugToScreen         Specifies whether to display
                                 error messages in the browser.

debug.trackResources             Enable tracking of JDBC
                                 resources that if not
                                 released will cause resource
                                 leaks/exhaustion in the
                                 database. Tracking imposes a
                                 performance overhead.

error.externalPath               The path to the external
                                 error pages.

error.responseFormat             Specifies in what format
                                 error responses should be
                                 rendered. Possible values:
                                 HTTP, JSON, AUTO. Defaults to
                                 AUTO.

feature.openservicebroker.excludeTo disable the Open Service
                                 Broker services available for
                                 the pool.

feature.sdw                      Enable Database Actions
                                 feature.

http.cookie.filter               A comma separated list of
                                 HTTP Cookies to exclude when
                                 initializing an Oracle Web
                                 Agent environment.

icap.port                        Specifies the Internet
                                 Content Adaptation Protocol
                                 (ICAP) port to virus scan
                                 files. Either icap.port or
                                 icap.secure.port are required
                                 to have a value when
                                 icap.server is set.

icap.secure.port                 Specifies the Internet
                                 Content Adaptation Protocol
                                 (ICAP) secure port to virus
                                 scan files. Either icap.port
                                 or icap.secure.port are
                                 required to have a value when
                                 icap.server is set.

icap.server                      Specifies the Internet
                                 Content Adaptation Protocol
                                 (ICAP) server name or IP
                                 address to virus scan files.

jdbc.DriverType                  The Oracle JDBC URL subtype
                                 that can have one of the
                                 values: thin, oci8. Defaults
                                 to thin.

jdbc.InactivityTimeout           Specify how long an available
                                 connection can remain idle
                                 before it is closed. The
                                 inactivity connection timeout
                                 is in seconds. Defaults to
                                 1800.

jdbc.InitialLimit                The initial size for the
                                 number of connections that
                                 will be created. Defaults to
                                 10.

jdbc.MaxConnectionReuseCount     Specify the maximum number of
                                 times to reuse a connection
                                 before it is discarded and
                                 replaced with a new
                                 connection.

jdbc.MaxLimit                    The maximum number of
                                 connections. Defaults to 10.

jdbc.MaxStatementsLimit          The maximum number of
                                 statements to cache for each
                                 connection. Defaults to 10.

jdbc.MinLimit                    The minimum number of
                                 connections. Defaults to 2.

jdbc.auth.admin.role             Identifies the database role
                                 that signifies the database
                                 user should get the SQL
                                 Administrator role.

jdbc.auth.enabled                Specifies if the PL/SQL
                                 Gateway calls can be
                                 authenticated using database
                                 users. Defaults to false. Set
                                 to true to enable feature.
                                 Oracle recommends not to use
                                 this feature. This feature
                                 used only to facilitate
                                 customers migrating from
                                 mod_plsql.

jdbc.cleanup.mode                Specifies how a pooled JDBC
                                 connection, and corresponding
                                 database session, is released
                                 when a request has been
                                 processed.

jdbc.driverName                  The name of the JDBC driver
                                 to use.

jdbc.statementTimeout            Specify how long a borrowed
                                 (in use) connection can
                                 remain unused before it is
                                 considered as abandoned and
                                 reclaimed. The abandoned
                                 connection timeout is in
                                 seconds.

json.sdo.geometry.output.geojson Specify that SDO Geometry
                                 data should be returned in
                                 GeoJSON format.

misc.defaultPage                 Default page (PL/SQL
                                 procedure) to invoke if the
                                 URL points to the context
                                 root of a database pool.
                                 Default value is apex.

misc.pagination.maxRows          Specifies the maximum number
                                 of rows that will be returned
                                 from a query when processing
                                 a RESTful service and that
                                 will be returned from a
                                 nested cursor in a result
                                 set. Affects all RESTful
                                 services generated through a
                                 SQL query, regardless of
                                 whether the resource is
                                 paginated. Defaults to 10000.

owa.trace.sql                    Boolean property that if true
                                 causes a trace of the SQL
                                 statements performed by
                                 Oracle Web Agent to be echoed
                                 to the log.

plsql.gateway.mode               Indicates if the PL/SQL
                                 Gateway functionality should
                                 be available for a pool or
                                 not. Value can be one of:
                                 disabled, direct or proxied.
                                 If direct is used, the pool
                                 will serve PL/SQL Gateway
                                 requests directly. If proxied
                                 is used, PLSQL_GATEWAY_CONFIG
                                 view is used to determine the
                                 user to proxy to.

procedure.rest.preHook           Name of a stored PL/SQL
                                 function that should be
                                 invoked prior to dispatching
                                 any REST request.

request.traceHeaderName          Denotes the name of the HTTP
                                 request header that uniquely
                                 identifies the request end to
                                 end as it passes through the
                                 various layers of the
                                 application stack. In Oracle
                                 this header is commonly
                                 referred to as the ECID
                                 (Entity Context ID).

resource.templates.enabled       Deprecated. Configuration
                                 property indicating if the
                                 legacy resource templates
                                 (APEX based REST) should be
                                 enabled or not. False by
                                 default. The
                                 resource-templates code base
                                 is not compatible with the
                                 single pool
                                 (ORDS_PUBLIC_USER)
                                 architecture so must be
                                 disabled.

restEnabledSql.active            Enable REST-Enabled SQL
                                 feature.

security.credentials.attempts    The maximum number of
                                 unsuccessful password
                                 attempts allowed. Enabled by
                                 setting a positive integer
                                 value. Defaults to -1.

security.credentials.file        The file where credentials
                                 are stored.

security.credentials.lock.time   The period to lock account
                                 that has exceeded maximum
                                 attempts. Defaults to 10
                                 minutes.

security.requestValidationFunctionSpecifies a validation
                                 function to determine if the
                                 requested procedure in the
                                 URL should be allowed or
                                 disallowed for processing.
                                 The function should return
                                 true if the procedure is
                                 allowed; otherwise, return
                                 false.

security.validationFunctionType  Indicate what type the
                                 security.requestValidationFunc
                                 ion is: javascript or plsql.
                                 Defaults to plsql.

security.verifySSL               Indicate whether HTTPS is
                                 available in your environment.

standalone.access.log            Path to the folder to store
                                 HTTP request access logs. If
                                 not specified then no access
                                 log will be generated.

standalone.binds                 Comma separated list of host
                                 names or IP addresses to
                                 identify a specific network
                                 interface on which to listen,
                                 default 0.0.0.0.

standalone.context.path          The context path where {0} is
                                 located, defaults to /ords

standalone.doc.root              Points to the location where
                                 static resources, to be
                                 served under the / root
                                 server path are located.

standalone.http.port             HTTP listen port, default 8080

standalone.https.cert            SSL certificate path. If you
                                 are providing the SSL
                                 certificate, you must specify
                                 the certificate location.

standalone.https.cert.key        SSL certificate key path. If
                                 you are providing the SSL
                                 certificate, you must specify
                                 the certificate key location.

standalone.https.host            SSL certificate hostname

standalone.https.port            HTTPS listen port, default
                                 8443

standalone.static.context.path   The Context path where
                                 Application Express static
                                 resources are located,
                                 defaults to /i

standalone.static.path           Path to the folder containing
                                 static resources required by
                                 APEX

standalone.stop.timeout          The period for Standalone
                                 Mode to wait to gracefully
                                 shutdown.
$

Comments (0)

Please to add comments

No comments yet. Be the first to comment!