Update documentation for configuration file server.env

jimblye commented 3 years ago

This update should coincide with the delivery of issue 14901 https://github.com/OpenLiberty/open-liberty/issues/14901

Two pages that I am aware of need to be updated:

Page 1: https://openliberty.io/docs/21.0.0.11/reference/config/server-configuration-overview.html Page 2: https://www.ibm.com/docs/en/was-liberty/core?topic=manually-customizing-liberty-environment

The documentation is different on these pages. It's probably 90% the same information, but just rewritten. There are some things included on one page and not the other and vice versa, but these seem to be errors of omission. Hopefully, the following documentation can be merged into both pages to be consistent.

On the first page, the updated documentation below replaces just the server.env section. On the second page, the updated documentation below replaces just the first bullet of the Procedure section.

-------- Updated Documentation -------

The server.env files are optional. These files are read by the bin/server shell script and specify environment variables that are primarily used to influence the behavior of the bin/server script. server.env files are read from the following locations in order:

${wlp.install.dir}/etc/

${wlp.user.dir}/shared/

${server.config.dir}/

If the same property is set in multiple locations, then the last value found is used. You can also specify these environment variables in the shell environment, but the server.env files take precedence over those variables.

The most common use of these files is to set the following environment variables:

JAVA_HOME - Indicates which JVM to use. If this is not set, the system default is used.

WLP_USER_DIR - Indicates the location of the usr directory that contains the server configuration This can only be set in the etc/server.env file because the other locations are relative to the usr directory.

WLP_OUTPUT_DIR - Indicates where the server writes files to. By default, the server writes to the directory structure that the configuration is read from. However, in some secure profiles the server configuration needs to be read-only so the server must write files to another location.

The server.env file is in KEY=value format, as shown in the following example:


JAVA_HOME=/opt/ibm/java
WLP_USER_DIR=/opt/wlp-usr

Key values must not contain spaces.
Empty lines are ignored.
Lines that start with the number sign (#) are ignored, except for "# enable_variable_expansion" which enables variable expansion on Linux.
There should be no white space surrounding the equal sign (=).
All characters are literal except when:

an expansion variable is specified on Windows (variable name between exclamation points.) For example !variableName! is replaced by the value of the variable

the caret (^) is used to escape a variable expansion character like the exclamation point (!)

variable expansion is enabled on Linux. In which case single quotes ('), double quotes (") and backslash (\) behave the same as in the shell environment. For example, surrounding a string in single quotes (') prevents the expansion of variables, while surrounding a string in double quotes (") does not, and backslash (\) is an escape character which removes the meaning of a special character.

As of 22.0.0.1, support for variable expansion has been added to the server.env file on Linux. This support has always existed on Windows, though it has never been documented. The syntax for specifying expansion variables is operating system dependent.

Specifying expansion variables on Windows

Variable expansion support is enabled by default on Windows. You specify expansion variables using Windows delayed expansion syntax: !variable_name! This is replaced by the value of the variable.

Example server.env file:

IBM_DIR=!ProgramFiles!\IBM
JAVA_HOME=!IBM_DIR!\java
WLP_USER_DIR=!USERPROFILE!\wlp-usr

Specifying expansion variables on Linux

By default, server.env files do not support variable expansion on Linux. The "value" in each KEY=value pair is interpreted literally. So, by default, you do not need to escape special characters, such as spaces. However, this changes when you enable support for variable expansion.

To enable support for variable expansion, add the following comment near the top of the server.env file: # enable_variable_expansion

Once enabled, you need to add quotation marks around values containing spaces, and it is necessary to escape inner quotation marks. For example, the inner quotation mark is escaped in the following value:

MESSAGE1='Don\'t do that'

Expansion variables are prefixed by a "$" and the variable name can also be enclosed in curley braces {}. For example $variable_name or ${variable_name}.

Example server.env file:

JAVA_HOME=/opt/ibm/java
WLP_USER_DIR=/home/${USER}/wlp-usr
LOG_DIR=${WLP_USER_DIR}/logs

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

For Review:

https://docs-draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#log-messages.

Regards, Ramkumar

dmuelle commented 2 years ago

initial peer review comments

the bulleted list that begins with "Key values must not contain spaces." needs an introduction. Something like "The following restrictions apply to server.env files."
make sure each bullet is a complete sentence
rewrite the bullet about literals so it is a complete sentence that doesn't end in "when"
rather than having a subsection for Windows and for mac, I'd recommend having a subsection about expansion variables that briefly explains what they are (1-2 sentences) and that the y are supported differently on Linux and Windows OS. Then explain the difference with examples
" For example, the inner quotation mark is escaped in the following value:" this example should be reworked- the quotation mark is actually an apostrophe, or is acting as one, which is potentially confusing
use monospace instead of quotes for “$”
"Example server.env file:" Make this a complete sentence

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

Review Comments incorporated.

Link: https://docs-draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html

Regards, Ramkumar

ramkumar-k-9286 commented 2 years ago

Conversation with the developer (for reference)

CC@dmuelle

Ramkumar K

Hi Jim. Needed some clarification With regards to the following issue : https://github.com/OpenLiberty/docs/issues/4882 Basically had 2 questions with regards to the expansion variables:

In the example shown for Linux, Example server.env file:
```
JAVA_HOME=/opt/ibm/java
WLP_USER_DIR=/home/${USER}/wlp-usr
LOG_DIR=$WLP_USER_DIR/logs
```
the expansion variable for JAVA_HOME seems missing. Wanted to clarify this with you.
the Second question is more of a general question: Where are the expansion variables defined?

Jim Blye

JAVA_HOME=/opt/ibm/java
WLP_USER_DIR=/home/${USER}/wlp-usr
LOG_DIR=${WLP_USER_DIR}/logs

JAVA_HOME is just getting set to a string in this example. It really doesn't add anything to the example. So the first line could be removed. I guess it just shows that you don't need a ${ } variable on the right-hand side. Note I have add { } around WLP_USER_DIR. I'm not sure if they are required in this case (it might not work), but it is safer to use the { }. I updated the comment in the issue.

Those can either be environment variables or shell variables. So basically, they are defined on the command line. In the example above, USER is a predefined variable by the OS.
But you could have another variable, say HTTP_PORT. You could define that one on the command line: HTTP_PORT=9080 that makes it a shell variable, meaning it is only accessible to the current shell and its children If you then do export HTTP_PORT Now it is an environment variable. So it is accessible to any new shells that are created.

Ramkumar K Hi Jim, based on what you mentioned above, was planning to add this as a part of the expansion variables explanation. Does this seem ok : You can specify expansion variables to include variables in the value definition of other variables. The values that these expansion variables supply can be defined as environment variables in your server configuration or shell variables in your shell environment.

Jim Blye --You can specify expansion variables to include variables in the value definition of other variables. Seems complicated. This is simpler: You can specify expansion variables in the value definition of other variables. The rest is ok.

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

Review Comments incorporated.

Link: https://docs-draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html

Regards, Ramkumar

dmuelle commented 2 years ago

I don' think you merged the changes- I dont see them on the draft site or in Git

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

Comments incorporated.

Link: https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html

Regards, Ramkumar

ramkumar-k-9286 commented 2 years ago

Hi Jim @jimblye

Could you review the following section: https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env

If additional changes are required, could you leave comments in this issue?

If the changes are as expected, could you add the Developer Reviewed label?

Regards, Ramkumar

jimblye commented 2 years ago

Review comments:

Two sentences, ending with a preposition. Though I think they were already there and not related to the new changes: WLP_OUTPUT_DIR -"Indicates where the server writes files to. By default, the server writes to the directory structure that the configuration is read from." WLP_OUTPUT_DIR -Indicates where the server writes files. By default, the server writes to the directory structure from which the configuration is read.

This could be more clear

All the characters are literal except in the case of expansion variables.
All the characters are literal except when expansion variables are enabled.

When I read the first bullet, I think that the syntax of an expansion variable might contain a character that is not taken literally. However, the meaning should go beyond that, because escape characters (^ on Windows, and \ on Linux) are used outside of expansion variables.

The following sentence doesn't have meaning by itself, or at least I don't think many will understand what it means: Expansion variable has the ability to access as well as manipulate the values of variables. Maybe this: Expansion variables are environment or shell variables which are replaced by their values. This sentence is Windows only: The caret sign ( ^ ) is used to escape a variable expansion character like the exclamation point (!). Maybe: The caret sign ( ^ ) is used to escape a variable expansion character like the exclamation point (!) on Windows.

The final example should be changed from: LOG_DIR=$WLP_USER_DIR/logs to: LOG_DIR=${WLP_USER_DIR}/logs It's just safer to use the ${ } syntax.

I think the rest is fine. This page also should be updated: https://www.ibm.com/docs/en/was-liberty/core?topic=manually-customizing-liberty-environment On this page it is just the first bullet of the Procedure section that needs to be updated. Though, I think that page should be exactly the same as the other page. Maybe they could just link to the same place.

ramkumar-k-9286 commented 2 years ago

Otherprops 22001+ Documentation for customizing the Liberty server manually is available on the [Open Liberty website](production url)

ramkumar-k-9286 commented 2 years ago

Hi Jim @jimblye

All the changes suggested have been incorporated:

https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env

A link has been added from the liberty document to the OL document.

If the changes are as expected, could you verify and add the Developer Reviewed label?

Regards, Ramkumar

CC @dmuelle

jimblye commented 2 years ago

I add developer review label here: https://github.com/OpenLiberty/docs/issues/4882Thanks, Jim Blye WebSphere Application Server Development - WCCM ----- Original message -----From: "Ramkumar" @.>To: "OpenLiberty/docs" @.>Cc: "jimblye" @.>, "Mention" @.>Subject: [EXTERNAL] Re: [OpenLiberty/docs] Update documentation for configuration file server.env (Issue #4882)Date: Tue, Dec 21, 2021 7:10 AM Hi Jim @jimblye All the changes suggested have been incorporated: https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env A link has been added from the liberty document to the ZjQcmQRYFpfptBannerStart

This Message Is From an External Sender This message came from outside your organization. ZjQcmQRYFpfptBannerEnd Hi Jim @jimblye All the changes suggested have been incorporated: https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env A link has been added from the liberty document to the OL document. If the changes are as expected, could you verify and add the Developer Reviewed label? Regards,Ramkumar CC @dmuelle —Reply to this email directly, view it on GitHub, or unsubscribe.Triage notifications on the go with GitHub Mobile for iOS or Android.You are receiving this because you were mentioned.Message ID: @.***>

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

Ran Acrolinx on the newly added server.env section, incorporated a few changes, removed + symbols.

Draft Link: https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env

For Peer Review.

Regards, Ramkumar

dmuelle commented 2 years ago

peer review

a few suggested edits:

WLP_USER_DIR- Indicates the location of the usr directory that contains the server configuration. Set only in the etc/server.env file, as other locations are relative to the usr directory. ---> WLP_USER_DIR- Indicates the location of the usr directory that contains the server configuration. Set this environment variable only in the etc/server.env file, because other locations are relative to the usr directory.

However, in some secure profiles, the server configuration needs to be read-only so the server must write files to another location. ---> However, in some secure profiles, the server configuration is read-only so the server must write files to another location.

Empty lines are to be ignored. ---> Empty lines are ignored.

Lines that start with the number sign ( # ) are ignored, except for the "# enable_variable_expansion" which enables variable expansion on Linux. ---> Lines that start with the number sign ( # ) are ignored, except for the # enable_variable_expansion line, which enables variable expansion on Linux.

All the characters are literal except when expansion variables are enabled. ---> All characters are literal except when expansion variables are enabled.

Example for expansion variable for windows is shown in the following server.env file. (use active voice) ---> The following server.env file example shows the syntax for expansion variables on Windows.

Expansion variables are prefixed by a $ and the variable name can also be enclosed in curly braces {}. For example, $variable_name or ${variable_name} ---> Expansion variables are prefixed by a dollar sign ($) and the variable name can optionally be enclosed in curly braces ({}), for example, $variable_name or ${variable_name}.

Example for expansion variable for Linux shown in the following server.env file: ---> The following server.env file example shows the syntax for expansion variables on Linux.

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

Peer Review comments have been incorporated.

Draft Link: https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env

Regards, Ramkumar

dmuelle commented 2 years ago

This looks good- I just have a couple minor suggestions

I think you could break up the longer paragraph about linux support to make it more readable (also make a few tweaks to sentences):

As of 22.0.0.1, support for variable expansion is provided to the server.env file on Linux. Expansion variables are prefixed by a dollar sign ( $ ) and the variable name can optionally be enclosed in curly braces ( {} ), for example, $variable_name or ${variable_name}. Single quotation marks ( ' ), double quotation marks ( " ), and backslash ( \ ) behave the same as in the shell environment. For example, placing a string in single quotation marks prevents the expansion of variables. Placing a string in double quotation marks does not prevent the expansion of variables, and backslash is an escape character that removes the meaning of a special character. By default, server.env files do not support variable expansion on Linux. The "value" in each KEY=value pair is interpreted literally. So, by default, you do not need to escape special characters, such as spaces. However, when you enable support for variable expansion, you need to escape special characters.

--->

In version 22.0.0.1 and later, Open Liberty supports expansion variables in server.env file on Linux systems. Expansion variables are prefixed by a dollar sign ( $ ) and the variable name can optionally be enclosed in curly braces ( {} ), for example, $variable_name or ${variable_name}.

When you enable expansion variables for Linux, single quotation marks ( ' ), double quotation marks ( " ), and backslash ( \ ) behave the same as in the shell environment. For example, placing a string in single quotation marks prevents the expansion of variables. Placing a string in double quotation marks does not prevent the expansion of variables, and the backslash is an escape character that removes the meaning of a special character.

By default, server.env files do not support variable expansion on Linux. The value in each KEY=value pair is interpreted literally and you do not need to escape special characters, such as spaces. However, when you enable support for variable expansion, you must escape special characters.

I think you could be more specific in introducing the Linux syntax, since the first line does not contain an expansion variable. It's useful for comparison, but should be acknowledged in the explanation.

The following server.env file example shows the syntax for expansion variables on Linux. ---> The following server.env file example shows the syntax for expansion variables on Linux. The values for the WLP_USER_DIR and LOG_DIR environment variables contain expansion variables.

otherwise LGTM

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

Suggested comments have been incorporated.

Draft Link: https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env

Regards, Ramkumar

dmuelle commented 2 years ago

a few minor things:

In version 22.0.0.1 and later, Open Liberty supports expansion variables in server.env file on Linux systems. ---> In version 22.0.0.1 and later, Open Liberty supports expansion variables in the server.env file on Linux systems.

The value in each KEY=value pair is interpreted literally ---> The value in each KEY=value pair is interpreted literally

With the variable expansion enabled, you need to add quotation marks around values that have spaces, and it is necessary to escape inner quotation marks. ---> When expansion variables are enabled, you must enclose any values that contain spaces in quotation marks. You must also escape inner quotation marks.

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

Suggested changes have been incorporated.

Draft Link: https://draft-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env

Regards, Ramkumar

dmuelle commented 2 years ago

LGTM- thanks. You can send this to staging when you get a chance

ramkumar-k-9286 commented 2 years ago

Hi David @dmuelle

File send to staging.

Staging site Link: https://docs-staging-openlibertyio.mybluemix.net/docs/22.0.0.1/reference/config/server-configuration-overview.html#server-env

Regards, Ramkumar

ramkumar-k-9286 commented 2 years ago

Topic is on vNExt and will publish with 22.0.0.1 on 1/18. Closing this issue

OpenLiberty / docs