diff --git a/modules/ROOT/pages/relational-database-connections-JDBC.adoc b/modules/ROOT/pages/relational-database-connections-JDBC.adoc index a639526489..6c7777a6bc 100644 --- a/modules/ROOT/pages/relational-database-connections-JDBC.adoc +++ b/modules/ROOT/pages/relational-database-connections-JDBC.adoc @@ -16,11 +16,18 @@ Java applications connect to and interact with relational databases through the Java Database Connectivity (JDBC) API. You can configure a data source and a JDBC driver so an application that is running on your Open Liberty server can connect with a relational database. -Applications communicate with relational databases to retrieve different kinds of information, such as flight schedules, product inventories, and customer purchase histories. The https://docs.oracle.com/javase/tutorial/jdbc/overview/index.html[JDBC API] provides an adapter layer between applications and relational databases by providing details about a database to an application in a standardized way. In Open Liberty, interactions with the JDBC API are configured by the xref:reference:feature/jdbc-4.2.adoc[Java Database Connectivity feature]. +Applications communicate with relational databases to retrieve different kinds of information, such as flight schedules, product inventories, and customer purchase histories. The https://docs.oracle.com/javase/tutorial/jdbc/overview/index.html[JDBC API] provides an adapter layer between applications and relational databases by providing details about a database to an application in a standardized way. In Open Liberty, interactions with the JDBC API are configured by the feature:jdbc[display=Java Database Connectivity] feature. +- <<#driver,JDBC driver library configuration>> +- <<#data,Data source configuration>> +- <<#examples,Common data source configuration examples>> +- <<#types,Data source types>> +- <<#app,Application configuration for relational database connections>> + +[#driver] == JDBC driver library configuration -To connect with a relational database, you need a JDBC driver, which is typically provided by the database vendor. You can configure JDBC drivers to define data sources, from which you obtain connections to the database. To configure a JDBC data source in your Open Liberty server configuration, you must enable the Java Database Connectivity feature and specify a library that contains your JDBC driver. In the following example, the `library` element specifies the location of the directory that contains a JDBC driver JAR file: +To connect with a relational database, you need a JDBC driver, which is typically provided by the database vendor. You can configure JDBC drivers to define data sources, from which you obtain connections to the database. To configure a JDBC data source in your Open Liberty server configuration, you must enable the Java Database Connectivity feature and specify a library that contains your JDBC driver. In the following `server.xml` file example, the `library` element specifies the location of the directory that contains a JDBC driver JAR file: [source,xml] @@ -90,8 +97,9 @@ task copyJDBC(type: Copy) { deploy.dependsOn 'copyJDBC' ---- -In this `build.gradle` file example, a `configurations` instance that is called `jdbcLib` is declared with a dependency for the driver. The `copyJDBC` task specifies that the driver JAR files are copied into the `jdbc` folder in the server configuration directory. Finally, a `deploy` dependency specifies that the driver must be copied to the server before the application is deployed so it can be available at run time. +In this `build.gradle` file example, a `configurations` instance that is called `jdbcLib` is declared with a dependency for the driver. The `copyJDBC` task specifies that the driver JAR files are copied into the `jdbc` folder in the server configuration directory. Finally, a `deploy.dependsOn` dependency specifies that the driver must be copied to the server before the application is deployed so it can be available at run time. +[#data] == Data source configuration You can configure any JDBC driver with Open Liberty, which includes built-in configuration for many common vendor databases. The following example shows the basic pattern to configure a data source in your `server.xml` file: @@ -112,7 +120,7 @@ You can configure any JDBC driver with Open Liberty, which includes built-in con In this example, the `dataSource` element references the library that contains the JDBC driver JAR file and specifies several JDBC vendor properties with the `properties` attribute. -Every JDBC driver provides a different collection of properties that can be configured on its `dataSource` implementation classes. If the JDBC driver data source has setter methods with a String or primitive parameter, you can configure these properties by specifying either a single `properties` or `properties.{_JDBC_VENDOR_TYPE_}` subelement under the `dataSource` element. Use a `properties.{_JDBC_VENDOR_TYPE_}` subelement if Liberty provides one for the JDBC driver that you are using. Otherwise, use a `properties` subelement. For more information about the vendor-specific `properties.{_JDBC_VENDOR_TYPE_}` subelements that Liberty provides, see the config:dataSource[] element. +Every JDBC driver provides a different collection of properties that you can configure on its `dataSource` implementation classes. If the JDBC driver data source has setter methods with a String or primitive parameter, you can configure these properties by specifying either a single `properties` or `properties.{_JDBC_vendor_type_}` subelement under the `dataSource` element. Use a `properties.{_JDBC_vendor_type_}` subelement if Liberty provides one for the JDBC driver that you are using. Otherwise, use a `properties` subelement. For more information about the vendor-specific `properties.{_JDBC_vendor_type_}` subelements that Liberty provides, see the config:dataSource[] element. The following example shows the basic configuration to specify JDBC vendor properties in the `properties` subelement: @@ -163,7 +171,7 @@ If you enable any Java EE or Jakarta EE features in Open Liberty, you can config ---- - +[#examples] == Common data source configuration examples The following examples show sample configurations for commonly used vendor databases. For applicable vendors, examples are provided for how to configure the database locally in a container for testing and development purposes: @@ -176,6 +184,7 @@ The following examples show sample configurations for commonly used vendor datab - <<#Oracle,Oracle>> - <<#Oracleucp,Oracle UCP>> - <<#Oraclerac,Oracle RAC>> +- <<#unknown,Configuration of databases that are unknown to Open Liberty>> [#PostgreSQL] === PostgreSQL configuration @@ -280,10 +289,10 @@ The following example shows a sample data source configuration for an Oracle dat [#Oracleucp] === Oracle UCP -https://docs.oracle.com/cd/E11882_01/java.112/e12265/intro.htm#BABHFGCA[Oracle Universal Connection Pool] (UCP) is a stand-alone JDBC connection pool. When you use Oracle UCP with Open Liberty, you are using the Oracle UCP connection pool instead of the Open Liberty built-in connection pooling functions. Some of the https://www.oracle.com/database/technologies/high-availability.html[Oracle high availability database] functions require the use of Oracle UCP. Support for Oracle UCP was added in Open Liberty version 19.0.0.4. +https://docs.oracle.com/cd/E11882_01/java.112/e12265/intro.htm#BABHFGCA[Oracle Universal Connection Pool] (UCP) is a stand-alone JDBC connection pool. When you use Oracle UCP with Open Liberty, you are using the Oracle UCP connection pool instead of the Open Liberty built-in connection pooling functions. Some of the https://www.oracle.com/database/technologies/high-availability.html[Oracle high availability database] functions require the use of Oracle UCP. Oracle UCP might require some properties, such as `user` and `password`, to be set in the `properties.oracle.ucp` element. -Because the Open Liberty connection pool is unavailable, some of the Open Liberty data source and connection manager configuration values are ignored. For most of those data source and connection manager properties, Oracle UCP provides equivalent functions. For more information, see the xref:reference:config/dataSource.adoc#dataSource/properties.oracle.ucp[properties.oracle.ucp element documentation]. +Because the Open Liberty connection pool is unavailable, some of the Open Liberty data source and connection manager configuration values are ignored. For most of those data source and connection manager properties, Oracle UCP provides equivalent functions. For more information, see the xref:reference:config/dataSource.adoc#dataSource/properties.oracle.ucp[properties.oracle.ucp] element documentation. Get the https://mvnrepository.com/artifact/com.oracle.database.jdbc/ucp[Oracle UCP JDBC driver from Maven Central]. The following example shows a sample data source configuration for Oracle UCP: @@ -322,9 +331,10 @@ The following example shows a sample data source configuration for an Oracle RAC ---- -In this example, `example-host-1` and `example-port-1` represent the host and port values for the first node, and `example-host-2` and `example-port-2` represent host and port values for the second node. The `FAILOVER` and `LOAD_BALANCE` Oracle parameters specify global configuration for both nodes. For more information about Oracle database parameters, see https://docs.oracle.com/cd/B28359_01/rac.111/b28254/admcon.htm#i1058057[the Oracle RAC documentation]. If you are not using Oracle services, then the value for `SERVICE_NAME` is your database name. If you are using Oracle services, then the value for `SERVICE_NAME` is the name of the service. You are not required to specify the Oracle login credentials as Oracle properties, xref:reference:feature/jdbc-4.3.adoc#_provide_security_credentials_for_data_source_authentication[other methods of database authentication] also work. Some Oracle RAC functions require the use of Oracle UCP, which is available only in Open Liberty version 19.0.0.4 and later. +In this example, `example-host-1` and `example-port-1` represent the host and port values for the first node, and `example-host-2` and `example-port-2` represent host and port values for the second node. The `FAILOVER` and `LOAD_BALANCE` Oracle parameters specify global configuration for both nodes. For more information about Oracle database parameters, see https://docs.oracle.com/cd/B28359_01/rac.111/b28254/admcon.htm#i1058057[the Oracle RAC documentation]. If you are not using Oracle services, then the value for `SERVICE_NAME` is your database name. If you are using Oracle services, then the value for `SERVICE_NAME` is the name of the service. You are not required to specify the Oracle login credentials as Oracle properties, xref:reference:feature/jdbc-4.3.adoc#_provide_security_credentials_for_data_source_authentication[other methods of database authentication] also work. Some Oracle RAC functions require the use of Oracle UCP. -== Configuration of databases that are unknown to Open Liberty +[#unknown] +=== Configuration of databases that are unknown to Open Liberty The following example shows a sample data source configuration for a relational database that Open Liberty does not recognize by default. Specify the type of the data source by using the `type` attribute of the `dataSource` element. The value for the `type` attribute can be one of the interface class names that are described in the <<#types,Data source types>> section. Then, specify the mapping of the interface class name to the driver implementation of that class on the `jdbcDriver` element, as shown in the following example: @@ -342,7 +352,7 @@ The following example shows a sample data source configuration for a relational -For more information, see the xref:reference:feature/jdbc-4.2.adoc[Java Database Connectivity feature]. +For more information, see the feature:jdbc[display=Java Database Connectivity] feature. [#types] == Data source types @@ -356,7 +366,7 @@ This basic form of data source lacks functions that are used by Liberty for opti This type of data source is enabled for xref:reference:feature/jdbc-4.2.adoc#_connection_pool_configuration[connection pooling]. It cannot participate as a two-phase capable resource in transactions that involve multiple resources. - `javax.sql.XADataSource` -This type of data source is enabled for connection pooling and is able to participate as a two-phase capable resource in transactions that involve multiple resources. The `javax.sql.XADataSource` data source type is essentially a superset of the capabilities that are provided by the `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource` data source types. However, some JDBC vendors might have subtle differences in behavior or limitations that are not spelled out in the JDBC specification. +This type of data source is enabled for connection pooling and is able to participate as a two-phase capable resource in transactions that involve multiple resources. The `javax.sql.XADataSource` data source type is a superset of the capabilities that are provided by the `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource` data source types. However, some JDBC vendors might have subtle differences in behavior or limitations that are not spelled out in the JDBC specification. - `java.sql.Driver` The `java.sql.Driver` driver implementation provides a basic way to connect to a database. This implementation requires a URL and is typically used in Java SE applications. Like `javax.sql.DataSource`, it does not provide interoperability that enhances connection pooling and cannot participate as a two-phase capable resource in transactions that involve multiple resources. To work with Open Liberty, this implementation must provide the `ServiceLoader` facility, which Open Liberty uses to discover JDBC driver implementations for a URL. @@ -375,6 +385,7 @@ If you use the Java Database Connectivity feature xref:reference:feature/jdbc-4. . `javax.sql.DataSource` . `javax.sql.XADataSource` +[#app] == Application configuration for relational database connections To use a data source that is configured in your `server.xml` file, you can either inject the data source or specify a lookup in your application code. The following examples assume that a `jndiName` value of `jdbc/myDB` is specified in the `dataSource` element in the `server.xml` file. diff --git a/modules/reference/pages/default-environment-variables.adoc b/modules/reference/pages/default-environment-variables.adoc index 22d779be50..75ada5fc92 100644 --- a/modules/reference/pages/default-environment-variables.adoc +++ b/modules/reference/pages/default-environment-variables.adoc @@ -6,19 +6,19 @@ // Contributors: // IBM Corporation // -:page-description: You can customize the Open Liberty environment by using specific variables +:page-description: You can configure environment variables in your Open Liberty `server.env` file to customize the Open Liberty environment. The properties are set in `KEY=value` format. :seo-title: Default environment variables -:seo-description: You can customize the Open Liberty environment by using specific variables to support the placement of product binary files and shared resources in the read-only file systems. +:seo-description: You can configure environment variables in your Open Liberty `server.env` file to customize the Open Liberty environment. The properties are set in `KEY=value` format. :page-layout: general-reference :page-type: general = Default environment variables -You can configure Open Liberty environment variables in your `server.env` file to customize the Open Liberty environment. -The `${wlp.install.dir}` configuration variable has an inferred location that is set to the parent of the directory that contains the launch script. +You can configure environment variables in your Open Liberty `server.env` file to customize the Open Liberty environment. The properties are set in `KEY=value` format. -For more information about the `server.env` file, see xref:reference:config/server-configuration-overview.adoc#server-env[Server configuration overview: server.env]. -The following table lists the default Open Liberty environment variables and gives a brief description for each variable: +For more information about configuring the `server.env` file, see xref:reference:config/server-configuration-overview.adoc#server-env[Server configuration overview: server.env]. + +The following table lists the default Open Liberty environment variables and gives a brief description for each variable: [%header] .Open Liberty default environment variables @@ -28,68 +28,66 @@ The following table lists the default Open Liberty environment variables and giv |JAVA_HOME -| Indicates which Java runtime environment (JRE) to use. +| Specifies which Java runtime environment (JRE) to use. If this variable is not set, the system default is used. |JVM_ARGS -| A list of command-line options, such as system properties or -X parameters, that are passed to the JVM when the server starts. - Any values that contain spaces must be enclosed in quotes. +| Specifies a list of command-line options, such as system properties or -X parameters, that are passed to the JVM when the server starts. + Any values that contain spaces must be enclosed in quotation marks. |LOG_DIR -| The directory that contains the log file. +| Specifies the directory that contains the log file. The default value is `%WLP_OUTPUT_DIR%/_serverName_/logs`. |LOG_FILE -| The log file name. +| Specifies the log file name. This log file is used only if the xref:reference:command/server-start.adoc[server start] command is run in the background through the start action. |SERVER_WORKING_DIR -| The directory that contains output files from the JVM that the server uses, such as the `javadump` files. The default value is the `${WLP_OUTPUT_DIR}/_serverName_` location. If this variable is set to a relative path, the resulting path is relative to this default location. For example, a value of `SERVER_WORKING_DIR=logs/javadumps` results in a path of `${WLP_OUTPUT_DIR}/_serverName_/logs/javadumps`. +| Specifies the directory that contains output files from the JVM that the server uses, such as the `javadump` files. The default value is the `${WLP_OUTPUT_DIR}/_serverName_` location. If this variable is set to a relative path, the resulting path is relative to this default location. For example, a value of `SERVER_WORKING_DIR=logs/javadumps` results in a path of `${WLP_OUTPUT_DIR}/_serverName_/logs/javadumps`. |VARIABLE_SOURCE_DIRS -| The directories that contain files to be loaded as configuration variables. +| Specifies the directories that contain files to be loaded as configuration variables. The default value is `${server.config.dir}/variables`. To define a list of directories as the value for this variable, separate each directory with the path separator for your operating system. For Windows, the path separator is a semicolon (`;`). For Unix-based systems, the path separator is a colon (`:`). |WLP_USER_DIR -| The user or custom configuration directory that is used to store +| Specifies the user or custom configuration directory that is used to store shared and server-specific configuration. - See the `_path_to_liberty_/wlp/README.TXT` file for details about shared resource locations. + See the `_path_to_liberty_/wlp/README.TXT` file in your server configuration for details about shared resource locations. A server configuration is at the `%WLP_USER_DIR%/servers/_serverName_` location. - The default value is the user directory in the installation directory. + The default value is the `usr` directory in the `wlp` directory. |WLP_OUTPUT_DIR -| The directory that contains output files for defined servers. +| Specifies the directory that contains output files for defined servers. This directory must have both read and write permissions for the user or users who start servers. By default, the server output logs and work area are stored - at the `%WLP_USER_DIR%/servers/_serverName_` location - alongside configuration and applications. + at the `%WLP_USER_DIR%/servers/_serverName_` location, + alongside configuration and application files. If this variable is set, the output logs and work area are stored at the `%WLP_OUTPUT_DIR%/_serverName_` location. |WLP_DEBUG_ADDRESS -| The port to use for running the server in debug mode. +| Specifies the port to use for running the server in debug mode. The default value is `7777`. | WLP_DEBUG_SUSPEND -| Specifies whether to suspend the JVM on startup. This variable can be - set to `y` to suspend the JVM on startup until a debugger attaches, - or set to `n` to start up without waiting for a debugger to attach. +| Specifies whether to suspend the JVM on startup. Set this variable to `y` to suspend the JVM on startup until a debugger attaches, + or set to `n` to start without waiting for a debugger to attach. The default value is `y`. | WLP_DEBUG_REMOTE -| Specifies whether to allow remote debugging. This variable can be set +| Specifies whether to allow remote debugging. Set this variable to `y` to allow remote debugging. By default, this value is not defined, which does not allow remote debugging on newer JDKs and JREs. - diff --git a/modules/reference/pages/feature/jwtSso/examples.adoc b/modules/reference/pages/feature/jwtSso/examples.adoc index ebf1093328..d61cbd72a4 100644 --- a/modules/reference/pages/feature/jwtSso/examples.adoc +++ b/modules/reference/pages/feature/jwtSso/examples.adoc @@ -2,8 +2,7 @@ With the JSON Web Token Single Sign-On feature, you can configure JSON Web Tokens (JWT) as an authentication mechanism for single-sign-on (SSO) authentication. -The JWT SSO cookie is configured by enabling the JSON Web Token Single Sign-On feature. -When a user is authenticated, Open Liberty creates a signed JWT as an SSO cookie and returns it to the browser. +When this feature is enabled and a user is authenticated, Open Liberty creates a signed JWT as an SSO cookie and returns it to the browser. The browser can then include the JWT cookie in subsequent requests to the Open Liberty server. === Change the token expiration time @@ -18,26 +17,28 @@ To customize the expiration time of a JWT, configure the `jwtBuilder` element, a ---- The `jwtBuilderRef` attribute refers to the `jwtBuilder` element with the `myBuilder` ID. -The `id` attribute for the `jwtBuilder` element that is named `myBuilder` identifies the JWT builder. -The `expiresInSeconds` attribute indicates the token expiration time that is set to 1800 seconds for a newly generated token. + +The `expiresInSeconds` attribute sets the token expiration time to 1800 seconds for newly generated tokens. === Disable JWT cookies By default, when a client is authenticated with Open Liberty through the JWT SSO feature, a JWT cookie is created and sent to the HTTP servlet. In the following example, the JWT cookies are disabled by specifying the `disableJwtCookie` attribute with a value of `true` in the `server.xml` file. -You can use a mechanism other than JWT cookies for authentication, as the JWT cookies are disabled in this example: + [source, xml] ---- ---- +You can then use a mechanism other than JWT cookies for authentication. + === Configure JWT SSO authentication for a subset of requests You can configure an authentication filter to specify whether certain requests for protected resources are authenticated with JWT SSO. -If the request meets the criteria that are specified in the authentication filter, then the request can authenticate with JWT to access the protected resource. +If the request meets the criteria that are specified in the authentication filter, then the request can authenticate with a JWT to access the protected resource. Conversely, if the request does not meet the criteria that are configured in the JWT SSO authentication filter, then the user is prompted to provide login credentials. -For more information, see xref:ROOT:authentication-filters.adoc[Authentication filters]. +If the JSON Web Token Single Sign-On feature is enabled but no authentication filter is configured, all requests that include a JWT cookie are processed by JWT SSO authentication. [source, xml] ---- @@ -48,8 +49,8 @@ For more information, see xref:ROOT:authentication-filters.adoc[Authentication f ---- -In the example, request URLs that contain the `/SimpleServlet` pattern are authenticated by using JWT SSO authentication. -If the JSON Web Token Single Sign-On feature is enabled but no authentication filter is configured, all requests that include a JWT cookie are processed by JWT SSO authentication. +In the example, request URLs that contain the `/SimpleServlet` pattern are authenticated by using JWT SSO authentication. For more information, see xref:ROOT:authentication-filters.adoc[Authentication filters]. + === Change JWT validation criteria @@ -79,7 +80,7 @@ To retrieve the JWT issuer public key from a JWK endpoint, specify the endpoint [source, xml] ---- - + ---- If you specify a non-default JWT builder, the JWK endpoint is `http(s)://:/jwt/ibm/api/(builderId)/jwk`, where `(builderId)` is the value of the `id` attribute for the `jwtBuilderelement`. @@ -87,5 +88,5 @@ In the following example, the configured `jwtSso` element results in a JWK endpo [source, xml] ---- - + ----