Network authentication service environment variables

You can use environment variables with network authentication service to affect how Generic Security Services (GSS) APIs and the Kerberos protocol APIs perform.

You can use environment variables to change the configuration and to manage the network authentication service on your network. The IBM® i operating system supports multiple ways to work with environment variables.

CL commands
  • ADDENVVAR
  • CHGENVVAR
  • RMVENVVAR
  • WRKENVVAR
For an example of using environment variables using the CL command, ADDENVVAR, see API trace tool. This set of environment variables allows you to create a log file that traces each of the Kerberos and GSS API calls. The API trace tool allows you to troubleshoot more advanced problems involving your Kerberos-enabled applications, problems that can occur during network authentication service configuration, and problems that can occur during Kerberos ticket requests.
C APIs
  • getenv()
  • putenv()
For descriptions and examples of these APIs, see the usage notes on the getenv() and the putenv() APIs.
Qshell commands
  • export -s env_var_name=value
In addition, you can define an environment variable file (envar file) containing entries of the form environment_variable=value. Any variables defined through the Qshell environment or with the CL commands override the same variables in the envar file. The _EUV_ENVAR_FILE environment variable can be used to specify the location of the file containing these entries.
_EUV_ENVAR_FILE

The name of the file that contains environment variable definitions. If this variable is not set, the default is to use the envar file located in the home directory (as specified by the _EUV_HOME or HOME environment variable).

Each line of the file consists of the variable name followed by an equal sign (=) followed by the variable value with no intervening blanks or other punctuation. The variable value consists of everything following the equal sign up to the end of the line (including any embedded and trailing blanks). Any line beginning with a pound sign (#) is treated as a comment line. You can continue a line by ending it with a backward slash (\). No trailing blanks can follow the backward slash. The _EUV_ must begin in column 1.

Environment variables are not set until the first time that a function in the security run time is invoked. Thus, it is mainly useful for setting environment variables that will be used by functions within the security run time, although it can be used to set environment variables that will be used by the application as well. In this case, the application should not rely on the environment variable values until after the security run time has been initialized. The user profile under which this program runs must have *X authority to each directory in the path preceding this file, and *R authority to this file.

_EUV_HOME and HOME
The security runtime home directory is set to the value of the _EUV_HOME environment variable. If this variable is not specified, the HOME variable is used to determine the security runtime home directory. If neither environment variable is set, the home directory that is configured in the currently running user profile is used. If the home directory does not exist, the current working directory is used. Limit public access to this directory to *EXCLUDE or *R.
_EUV_SEC_KRB5CCNAME_FILE
The name of the file used to locate the default Kerberos credentials cache. If this variable is not set, the default is to use the krb5ccname file located in the security runtime home directory. The running user profile must have *X authority to each directory in the path name preceding this file. If the file does not yet exist, the running user profile must have *WX authority to the parent directory that contains this file. The user must ensure that public access to the parent directory is limited to prevent a malicious user from changing the credentials cache file that is used.
_EUV_SVC_MSG_LOGGING
The target where messages are logged. The following values are valid:
NO_LOGGING
Suppress all messages. This is the default.
STDOUT_LOGGING
Write all messages (informational and error) to stdout, and write error messages to stderr.
STDERR_LOGGING
Write informational messages to stdout and error messages to stderr.
_EUV_SVC_MSG_LEVEL
The message level when logging messages. Messages that do not meet this criterion are suppressed. The default is to log all messages. The following values are valid:
FATAL
Only unrecoverable messages are logged.
ERROR
Only unrecoverable and error messages are logged.
USER
Only unrecoverable, error, and user messages are logged.
WARNING
Only unrecoverable, error, user, and warning messages are logged.
NOTICE
Only unrecoverable, error, user, warning, and notice messages are logged.
VERBOSE
All messages are logged.
_EUV_SVC_STDOUT_FILENAME
The fully qualified name of the file to receive standard output messages. If this environment variable is not defined, messages are written to stdout. The currently running user profile must have *X authority to each directory in the path preceding this file and *WX authority to the parent directory that contains this file.
_EUV_SVC_STDERR_FILENAME
The fully qualified name of the file to receive standard error messages. If this environment variable is not defined, messages are written to stderr. The currently running user profile must have *X authority to each directory in the path preceding this file and *WX authority to the parent directory that contains this file.
_EUV_SVC_DBG_MSG_LOGGING
Whether debug messages are generated. The default is to suppress debug messages. Logging of debug messages should not be enabled unless requested by IBM service, as it can severely affect performance. The following values are valid:
  • 0 Suppress debug messages
  • 1 Write debug messages
_EUV_SVC_DBG

The subcomponents and levels for the debug messages. Debug messages for a particular subcomponent are not logged unless the subcomponent is included in the _EUV_SVC_DBG list and the debug message level is greater than or equal to the specified level. Use an asterisk (*) to specify all subcomponents.

The subcomponent list consists of a subcomponent name and a debug level separated by a period. You can specify multiple subcomponents by separating the entries with commas. For example, _EUV_SVC_DBG=*.1,KRB_CCACHE.8 enables debug level 1 for all subcomponents and debug level 8 for the KRB_CCACHE subcomponent. You can specify the following subcomponents:
  • KRB_API
  • KRB_GENERAL
  • KRB_CCACHE
  • KRB_RCACHE
  • KRB_CRYPTO
  • KRB_GSSAPI
  • KRB_KEYTAB
  • KRB_LIB
  • KRB_ASN1
  • KRB_OS
  • KRB_KDC
  • KRB_KDB
  • KRB_KUT
_EUV_SVC_DBG_FILENAME
The fully qualified name of the file to receive debug messages. If this environment variable is not defined, debug messages are written to the file specified by the _EUV_SVC_STDOUT_FILENAME. If _EUV_SVC_STDOUT_FILENAME is not specified, then debug messages are written to stdout. The currently running user profile must have *X authority to each directory in the path preceding this file and *WX authority to the parent directory that contains this file.
KRB5_CONFIG
One or more configuration file names separated by colons. The default configuration file is /QIBM/UserData/OS400/NetworkAuthentication/krb5.conf. The currently running user profile must have *X authority to each directory in the path preceding these configuration files and *R authority to the configuration files.
The file krb5.conf is divided into sections whose names are enclosed in brackets. Within sections, the group values are enclosed in braces. In V5R4 and earlier releases, you can use the corresponding trigraphs instead of the brackets and braces as shown in the following table.
Character Trigraph
[ (left bracket) ??(
] (right bracket) ??)
{ (left brace) ??<
} (right brace) ??>

However, by default, the systems that are running IBM i 6.1 are configured to use brackets and braces instead of the trigraphs. If you are not using a Java™ Kerberos client, you can set your system to use trigraphs. To use trigraphs on your system, you can change the first letter of the QUSRSYS/QKRBTRIGRA data area from the default N to Y by using the Change Data Area (CHGDTAARA) CL command.

KRB5CCNAME
The default name for the credentials cache file, which is specified as type:name. The supported types are FILE and MEMORY. The default is to perform FILE-based credentials caching in the /QIBM/UserData/OS400/NetworkAuthentication/creds directory. If the default is used, no authority setup is needed. If a FILE-based credentials cache file is specified, then the currently running user profile must have *X authority to each directory in the path. It must have *WX authority to the parent directory when the cache file is first created and *RW authority to the cache file. If the cache file is being deleted, it must have *OBJEXIST authority to the cache file.
KRB5_KTNAME
The default key table name. If not specified, the file specified by the default_keytab_name configuration entry in the configuration file is used. If the configuration entry is not specified, the default file is /QIBM/UserData/OS400/NetworkAuthentication/keytab/krb5.keytab. The user profile that is currently running must have *X authority to each directory in the path. If the file is being created, it must also have *WX authority to the parent directory. If the file is being updated, it must have *RW authority to the file. Specific authorities that are needed are documented under the Qshell commands and the runtime APIs.
KRB5RCACHETYPE
The default replay cache type. It defaults to dfl.
KRB5RCACHENAME
The default replay cache name. If not specified, the Kerberos run time generates a name.
KRB5RCACHEDIR
The default replay cache directory. It defaults to /QIBM/UserData/OS400/NetworkAuthentication/replay.