Library Configuration

Introduction

This chapter describes the run-time configuration parameters of the NCBI C++ Toolkit libraries. Such parameters change the default behavior of applications built using the Toolkit.

Configuration parameters can be set by environment variables, entered into a configuration file, defined by code, or any combination of those methods. Note: If a parameter is specified in both a configuration file and the environment, the environment takes precedence. The methods supported by each library and application are described below.

Chapter Outline

The following is an outline of the topics presented in this chapter:

Defining and Using Parameters

The following sections discuss the methods that libraries can use to define configuration parameters, and the corresponding methods that client applications can use to specify values for those parameters.

CParam

Note: The preferred way for libraries to define their configuration parameters is with the macros in the CParam class (e.g. NCBI_PARAM_DECL). More details on the CParam class and its macros are presented in an earlier chapter. Libraries that use CParam can get configuration parameters using either the registry or the environment. Also, the CParam value can be stored and accessed on different levels: globally (application wide) and/or per-thread (TLS-like) and/or locally (cached within a CParam instance). Note that the name of an environment variable linked to a CParam can be customized or follow the default naming convention, so you have to look up the actual name used in the tables below before setting a configuration parameter using the environment.

Registry

If the CParam class cannot be used, the registry (configuration file) may be used to load, access, modify and store the values read from a configuration file. For libraries that use the registry, client applications can set the library configuration parameters using either the registry or the environment. In these cases the environment variable must follow the default naming convention.

These environment variables can be used to specify where to look for the registry.

Table 1. Registry configuration parameters

Purpose Environment variable Valid values
If this variable is defined, the value is an extra-high-priority configuration file whose entries override those from other configuration files. NCBI_CONFIG_OVERRIDES a valid path
If this variable is defined, use it exclusively as the registry search path. NCBI_CONFIG_PATH a valid path
If this variable is not defined, append the current directory and home directory to the registry search path (after NCBI_CONFIG_PATH). NCBI_DONT_USE_LOCAL_CONFIG anything
If this variable is defined, append the value to the registry search path (after the home directory). NCBI a valid path
For Windows: If this variable is defined, append the value to the registry search path (after NCBI). For non-Windows, this variable is not checked and /etc is appended to the registry search path (after NCBI). SYSTEMROOT a valid path
If this variable is not defined, attempt to load a low-priority system-wide registry (ncbi.ini on Windows; .ncbirc on non-Windows). Note: the system-wide registry will not be loaded if it contains the DONT_USE_NCBIRC entry in the NCBI section. NCBI_DONT_USE_NCBIRC anything

The registry is case-insensitive for section and entry names. More details on the registry are presented in an earlier chapter.

Environment

For configuration parameters defined by either CParam or the registry, there is an equivalent environment variable having the form NCBI_CONFIG__<section>__<name> (note the double-underscores preceding <section> and <name>). The equivalent form is all uppercase.

Note: Registry section and entry names may contain some characters that are difficult or impossible to use in environment variable names on some platforms. To obtain corresponding environment variable names, you can and should make some formal substitutions as detailed below. For example, the equivalent environment variable for [FastCGI]
WatchFile.Name is NCBI_CONFIG__FASTCGI__WATCHFILE_DOT_NAME.

Character Substitution
'.' (dot, full stop, period) _DOT_
'-' (hyphen, minus) _HYPHEN_
'/' ([forward] slash, solidus) _SLASH_
' ' (space) _SPACE_

Note: Environment variables are case-sensitive on many platforms. Therefore, when setting a configuration parameter via the environment, be sure to use the case shown in the tables below.

Some configuration parameters can only be set with an environment variable - for example, DIAG_SILENT_ABORT. In such cases, there is no corresponding registry entry.

Non-Specific Parameters

The following sections discuss configuration parameters that are not library-specific.

Logging

The application log consists of diagnostic messages. Some of them are available only in debug builds. Others - namely, those produced by the ERR_POST or LOG_POST macros - can be redirected into a file. Normally, the name and location of the application log is specified using the logfile command-line argument.

Log messages have different levels of severity. Setting the logging level is described in the next chapter Diagnostic Trace

These parameters tune the usage and behavior of the application log file.

Table 2. Log file configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
If true, post log messages when configuration parameters are read by one of the ncbi::g_GetConfig*() functions. Messages include the parameter; the value; and whether the value came from the application registry, the environment, or a default value. [N/A]
N/A

NCBI_CONFIG__NCBI__CONFIG_DUMP_VARIABLES
Boolean  b (none)
Used by logging framework if the real client IP can not be obtained. [LOG]
Client_Ip

NCBI_LOG_CLIENT_IP
a valid IPv4 or IPv6 address ””
Reset the log file to the specified file. [LOG]
File

NCBI_CONFIG__LOG__FILE  c
a valid file name ””
Defines the default hit ID, which is used for application and for any request which has no explicit hit ID set. [Log]
Hit_Id

NCBI_LOG_HIT_ID
any valid PHID string ””
Same as NCBI_LOG_HIT_ID, but passed through HTTP headers. Has priority over NCBI_LOG_HIT_ID. [Log]
Http_Hit_Id

HTTP_NCBI_PHID
any valid PHID string ””
Same as NCBI_LOG_SESSION_ID, but passed through HTTP headers. Has priority over NCBI_LOG_SESSION_ID. [Log]
Http_Session_Id

HTTP_NCBI_SID
any valid session ID string “UNK_SESSION”
Specify when to use the File, NoCreate, Truncate, and TryRootLogFirst registry parameters shown in this table. Note: those parameters will only be used if the log file has not been set already or if IgnoreEnvArg is set to true. [LOG]
IgnoreEnvArg

NCBI_CONFIG__LOG__IGNOREENVARG  c
Boolean  a false
Specify the maximum number of sub-PHIDs that can be reported to the AppLog by a single request. [Log]
Issued_SubHit_Limit

LOG_ISSUED_SUBHIT_LIMIT
unsigned integer 200
Log all app arguments before application run. The extra message starts with a “LogAppArguments=true” pair. [LOG]
LogAppArguments

DIAG_LOG_APP_ARGUMENTS [sic]
Boolean  a ””
Log all environment variables as an ‘extra’ before application run. The extra message starts with a “LogAppEnvironment=true” pair. [LOG]
LogAppEnvironment

DIAG_LOG_APP_ENVIRONMENT [sic]
Boolean  a ””
Log all environment variables as an ‘extra’ after application run. The extra message starts with a “LogAppEnvironment=true” pair. [LOG]
LogAppEnvironmentOnStop

DIAG_LOG_APP_ENVIRONMENT_ON_STOP [sic]
Boolean  a ””
Log application executable path before application run. The extra message starts with a “LogAppPath=true” pair. [LOG]
LogAppPath

DIAG_LOG_APP_PATH [sic]
Boolean  a ””
Log all registry variables as an ‘extra’ before application run. The extra message starts with a “LogAppRegistry=true” pair. [LOG]
LogAppRegistry

DIAG_LOG_APP_REGISTRY [sic]
Boolean  a ””
Log all registry variables as an ‘extra’ after application run. The extra message starts with a “LogAppRegistry=true” pair. [LOG]
LogAppRegistryOnStop

DIAG_LOG_APP_REGISTRY_ON_STOP [sic]
Boolean  a ””
Log memory and CPU consumed by application as an ‘extra’ after application run, just before stop. The extra message starts with a “LogAppResUsage=true” pair. [LOG]
LogAppResUsageOnStop

DIAG_LOG_APP_RESUSAGE_ON_STOP [sic]
Boolean  a ””
Set [LOG]LogAppRegistry, [LOG]LogAppRegistryOnStop, [LOG]LogAppEnvironment, [LOG]LogAppEnvironmentOnStop, [LOG]LogAppArguments, [LOG]LogAppPath to the one specified value [LOG]
LogAppRunContext

DIAG_LOG_APP_RUN_CONTEXT [sic]
Boolean  a ””
The listed environment variables will be logged as an ‘extra’ after each ‘request-start’ message. The extra message starts with a “LogEnvironment=true” pair. [LOG]
LogEnvironment

DIAG_LOG_ENVIRONMENT [sic]
space separated list of environment variable names ””
The listed registry entries will be logged as an ‘extra’ after each ‘request-start’ message. The extra message starts with a “LogRegistry=true” pair. [LOG]
LogRegistry

DIAG_LOG_REGISTRY [sic]
space separated list of registry section:name values ””
Do not create the log file if it does not exist already. [Log]
NoCreate

NCBI_CONFIG__LOG__NOCREATE  c
Boolean  b false
Specifies what to do if an invalid page hit ID is encountered. Valid PHIDs match the regex: [A-Za-z0-9:@_-]+(\.[0-9]+)* [Log]
On_Bad_Hit_Id

LOG_ON_BAD_HIT_ID
“Allow”, “AllowAndReport”, “Ignore”, “IgnoreAndReport”, “Throw” “AllowAndReport”
Specifies what to do if an invalid session ID is encountered. Valid session IDs match the format specified by LOG_SESSION_ID_FORMAT. [Log]
On_Bad_Session_Id

LOG_ON_BAD_SESSION_ID
“Allow”, “AllowAndReport”, “Ignore”, “IgnoreAndReport”, “Throw” “AllowAndReport”
Turn performance logging on or off (globally). [Log]
PerfLogging

LOG_PerfLogging  c
Boolean  b false
Defines the default session ID, which is used for any request which has no explicit session ID set. [Log]
Session_Id

NCBI_LOG_SESSION_ID
any valid session ID string “UNK_SESSION”
Specifies which format rule to check session IDs against:
for “Ncbi” use ^[0-9]{16}_[0-9]{4,}SID$
for “Standard” use ^[A-Za-z0-9_.:@-]+$
for “Other” use ^.*$ (i.e. anything is valid).
[Log]
Session_Id_Format

LOG_SESSION_ID_FORMAT
“Ncbi”, “Standard”, “Other” “Standard”
If this parameter is defined, use the CSysLog facility setting when posting. [LOG]
SysLogFacility

NCBI_CONFIG__LOG__SYSLOGFACILITY  c
any non-empty string (none)
Truncate the log file – i.e. discard the contents when opening an existing file. [Log]
Truncate

LOG_TRUNCATE
Boolean  b false
Specify whether to try creating the log file under /log before trying other locations (e.g. a location specified by the registry or by NCBI_CONFIG__LOG__FILE). [LOG]
TryRootLogFirst

NCBI_CONFIG__LOG__TRYROOTLOGFIRST  c
Boolean  a false
If true, default to logging warnings when unsafe static array types are copied. [NCBI]
STATIC_ARRAY_COPY_WARNING

NCBI_STATIC_ARRAY_COPY_WARNING
Boolean  b false
If true, log warnings for unsafe static array types. [NCBI]
STATIC_ARRAY_UNSAFE_TYPE_WARNING

NCBI_STATIC_ARRAY_UNSAFE_TYPE_WARNING
Boolean  b true

a case-insensitive: true, t, yes, y, false, f, no, n

b case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

c environment variable name formed from registry section and entry name

Diagnostic Trace

Severity level is the same for all macros (ERR_POST, LOG_POST, _TRACE). DIAG_TRACE enables _TRACE output regardless of the severity level. So, if your severity level is Warning and DIAG_TRACE is set, you will see Warnings (and above) and Traces but not Infos. This chapter tells more about logging severity: Setting Diagnostic Severity Levels

These parameters tune the visibility and contents of diagnostic messages produced by _TRACE, LOG_POST or ERR_POST macros.

See Table 3.

Table 3. Diagnostic trace configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Specify the severity level threshold for posting diagnostic messages – i.e. less severe messages will not be posted. Special case: Trace – print all messages and show Trace level messages. Note: If the parameter is set then the function ncbi::SetDiagPostLevel() is ignored - except for setting the level to eDiag_Trace, in which case Trace level messages will be shown anyway. [DEBUG]
DIAG_POST_LEVEL

DIAG_POST_LEVEL
CI  b: Info, Warning, Error, Critical, Fatal, Trace (none)
Messages with Trace level will be shown if this parameter is given any value. [DEBUG]
DIAG_TRACE

DIAG_TRACE or NCBI_CONFIG__DEBUG__DIAG_TRACE  c
any non-empty string (none)
Specify a file that stores a mapping of error codes to their descriptions. [DEBUG]
MessageFile

NCBI_CONFIG__DEBUG__MESSAGEFILE  c
a valid file name (none)
Specify the minimum severity that will result in the stack trace being added to diagnostic messages. [DEBUG]
Stack_Trace_Level

DEBUG_STACK_TRACE_LEVEL
CI  b: Info, Warning, Error, Critical, Fatal, Trace Fatal
Specify the maximum number of entries to be listed in a stack trace. All stack trace entries above the specified level are not printed. [DEBUG]
Stack_Trace_Max_Depth

DEBUG_STACK_TRACE_MAX_DEPTH
a positive integer 200
Specify the maximum number of messages that can be posted to the AppLog within the AppLog period. [Diag]
AppLog_Rate_Limit

DIAG_APPLOG_RATE_LIMIT
unsigned integer or OFF 50000
Specify the AppLog period in seconds. [Diag]
AppLog_Rate_Period

DIAG_APPLOG_RATE_PERIOD
unsigned integer 10
Specify whether context properties should be automatically printed when set or changed. [Diag]
AutoWrite_Context

DIAG_AUTOWRITE_CONTEXT
Boolean  a false
Specify the maximum number of diagnostic messages to collect. Messages beyond the limit will result in erasing the oldest message. [Diag]
Collect_Limit

DIAG_COLLECT_LIMIT
size_t 1000
Disable all Applog messages (start/stop, request start/stop, extra). [Diag]
Disable_AppLog_Messages

DIAG_DISABLE_APPLOG_MESSAGES
Boolean  a false
Specify the maximum number of messages that can be posted to the ErrLog within the ErrLog period. [Diag]
ErrLog_Rate_Limit

DIAG_ERRLOG_RATE_LIMIT
unsigned integer or OFF 5000
Specify the ErrLog period in seconds. [Diag]
ErrLog_Rate_Period

DIAG_ERRLOG_RATE_PERIOD
unsigned integer 1
Limit the log file size, and rotate the log when it reaches the limit. [Diag]
Log_Size_Limit

DIAG_LOG_SIZE_LIMIT
non-negative long integer 0
If “On”, then replace newlines in diagnostic messages with a semicolon.
N.B. Newlines are replaced in-place by “;” - they are not escaped.
[Diag]
Merge_Lines

DIAG_MERGE_LINES
“Default”, “Off”, or “On” “Default” (which means “Off”)
Use the old output format if the flag is set. [Diag]
Old_Post_Format

DIAG_OLD_POST_FORMAT
Boolean  a true
Specify a diagnostics post filter string (see an earlier chapter for more detail on filtering). [DIAG]
POST_FILTER

NCBI_CONFIG__DIAG__POST_FILTER  c
see the syntax rules (none)
Print the system TID rather than CThread::GetSelf(). [Diag]
Print_System_TID

DIAG_PRINT_SYSTEM_TID
Boolean  a false
Specify the minimum severity that will activate Tee_To_Stderr. See the Tee Output to STDERR section. [Diag]
Tee_Min_Severity

DIAG_TEE_MIN_SEVERITY
CI  b: Info, Warning, Error, Critical, Fatal, Trace Warning (debug); Error (release)
Duplicate messages to stderr. See the Tee Output to STDERR section. [Diag]
Tee_To_Stderr

DIAG_TEE_TO_STDERR
Boolean  a false
Specify a diagnostics trace filter string (see an earlier chapter for more detail on filtering). [DIAG]
TRACE_FILTER

NCBI_CONFIG__DIAG__TRACE_FILTER  c
see the syntax rules (none)
Specify the maximum number of messages that can be posted to the TraceLog within the TraceLog period. [Diag]
TraceLog_Rate_Limit

DIAG_TRACELOG_RATE_LIMIT
unsigned integer or OFF 5000
Specify the TraceLog period in seconds. [Diag]
TraceLog_Rate_Period

DIAG_TRACELOG_RATE_PERIOD
unsigned integer 1
If true and AppLog severity is not locked, print the current GMT time in diagnostic messages; otherwise print local time. [Diag]
UTC_Timestamp

DIAG_UTC_TIMESTAMP
Boolean  a false

a case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

b CI = case-insensitive

c environment variable name formed from registry section and entry name

Run-Time

Run-time configuration parameters allow specifying memory size limit, CPU time limit, and memory allocation behavior. Note: not all operating systems support these parameters.

Table 4. Run-time configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Controls whether to enable libbackward’s support for printing stack traces on segmentation faults and the like; the default is based on the build-time flag --with-backward-cpp-sig.

NB: Code bypassing CNcbiApplication but interested in this feature should explicitly call CStackTrace::s_HonorSignalHandlingConfiguration().
[Debug]
Trace_Fatal_Signals

DEBUG_TRACE_FATAL_SIGNALS
Boolean  a varies by build-time configuration, but false for standard builds
Set a CPU time limit for the application in seconds. [NCBI]
CpuTimeLimit

NCBI_CONFIG__NCBI__CPUTIMELIMIT  b
non-negative integer 0 (unlimited)
Set a memory size limit for the application. [NCBI]
MemorySizeLimit

NCBI_CONFIG__NCBI__MEMORYSIZELIMIT  b
A positive integer percent (e.g. “70%”) or an optionally suffixed non-negative real number (e.g. “123456789”, “100MiB”, or “1.25 G”).

A percent limit is relative to the total system memory.

No suffix means the given value is in MiB; a “B” suffix means the value is in bytes.

If there is a suffix, there can be spaces between the number and the suffix. The default units are decimal (i.e. powers of 1000) - e.g. “MB”. The final “B” is optional for decimal units (e.g. “M”). You can use “i” to indicate binary units (i.e. powers of 1024) – e.g. “MiB”.

Supported suffix characters are: “K”, “M”, “G”, “T”, “P”, and “E”.

Suffixes are not case-sensitive.
0 (unlimited)
Specify the method for filling allocated memory. [NCBI]
MEMORY_FILL

NCBI_MEMORY_FILL
CI  c: none, zero, pattern pattern

a case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

b environment variable name formed from registry section and entry name

c CI = case-insensitive

Abnormal Program Termination

These parameters specify how to handle abnormal situations when executing a program.

Table 5. Abnormal program termination configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
If this parameter is defined, abort the program if a CException is thrown. [DEBUG]
ABORT_ON_THROW

NCBI_CONFIG__DEBUG__ABORT_ON_THROW  c
any non-empty string (none)
Specify whether the NCBI application framework should catch exceptions that are not otherwise caught. [Debug]
Catch_Unhandled_Exceptions

DEBUG_CATCH_UNHANDLED_EXCEPTIONS
Boolean  a true
Specify whether ncbi::Abort() will call _ASSERT(false). Note: this only applies to MSVC. [Diag]
Assert_On_Abort

DIAG_ASSERT_ON_ABORT
Boolean  a false
If this parameter is true, abort the program if a CObjectException is thrown. [NCBI]
ABORT_ON_COBJECT_THROW

NCBI_ABORT_ON_COBJECT_THROW
Boolean  a false
If this parameter is true, abort the program on an attempt to access or release a NULL pointer stored in a CRef object. [NCBI]
ABORT_ON_NULL

NCBI_ABORT_ON_NULL
Boolean  a false
Specify what to do when ncbi::Abort() is called. When the variable is set to a “yes” value, Abort() will call exit(255). When the variable is set to a “no” value, Abort() will call abort(). When the variable is not set, Abort() will call exit(255) for release builds and abort() for debug builds - unless compiled with MSVC and the DIAG_ASSERT_ON_ABORT parameter is true, in which case Abort() will call _ASSERT(false). [N/A]
N/A

DIAG_SILENT_ABORT
Boolean  b (none)

a case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

b case-insensitive: y, 1, n, 0

c environment variable name formed from registry section and entry name

NCBI

These parameters tune generic NCBI C++ Toolkit-wide behavior.

Table 6. NCBI C++ Toolkit-wide configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Specify whether throwing an exception of at least Critical severity will cause an immediate abort(). [EXCEPTION]
Abort_If_Critical

EXCEPTION_ABORT_IF_CRITICAL
Boolean  a false
Specify the minimum severity that will result in the stack trace being added to exceptions. [EXCEPTION]
Stack_Trace_Level

EXCEPTION_STACK_TRACE_LEVEL
CI  b: Trace, Info, Warning, Error, Critical, Fatal Critical
A single path to check for common data files via g_FindDataFile(). Takes a lower precedence than paths in NCBI_DATA_PATH. [NCBI]
Data

NCBI_CONFIG__NCBI__DATA  c
a valid path ””
A list of paths (delimited in the style of the OS) to check for common data files via g_FindDataFile(). [NCBI]
DataPath

NCBI_DATA_PATH
a delimited list of valid paths ””
Specify how read-only files are treated on Windows during a remove request. [NCBI]
DeleteReadOnlyFiles

NCBI_CONFIG__DELETEREADONLYFILES
Boolean  a false
Specify whether the API classes should have logging turned on. [NCBI]
FileAPILogging

NCBI_CONFIG__FILEAPILOGGING
Boolean  a DEFAULT_LOGGING_VALUE
Declare how umask settings on Unix affect creating files/directories in the File API. [NCBI]
FileAPIHonorUmask

NCBI_CONFIG__FILEAPIHONORUMASK
Boolean  a false
Specify whether to load plugins from DLLs. [NCBI]
Load_Plugins_From_DLLs

NCBI_LOAD_PLUGINS_FROM_DLLS
Boolean  a LOAD_PLUGINS_FROM_DLLS_BY_DEFAULT
Specify the directory to use for temporary files. [NCBI]
TmpDir

NCBI_CONFIG__NCBI__TMPDIR  c
a valid path ””
Specify the file name of a Unicode-to-ASCII translation table. [NCBI]
UnicodeToAscii

NCBI_CONFIG__NCBI__UNICODETOASCII  c
a valid path ””
Safety switch to turn async write off (making write blocking) for all CAsyncWriteCache instances. [NCBI]
cache_async_write

NCBI_CONFIG__NCBI__CACHEASYNCWRITE
Boolean  a false

a case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

b CI = case-insensitive

c environment variable name formed from registry section and entry name

Library-Specific Parameters

The following sections discuss library-specific configuration parameters.

Connection

These parameters affect various aspects of internet connections established by the connection library. See the Networking and IPC chapter for a description of the corresponding network information structure.

Table 7. Connection library configuration parameters

Purpose [Registry section]
Registry name

Environment variable (See Note 2)
Valid values Default
Service-specific parameters follow this form.
(See Note 1)
[<service>]
CONN_<param_name>

<service>_CONN_<param_name>
   
Global parameters follow this form.
(See Note 1)
[CONN]
<param_name>

CONN_<param_name>
   
Specify arguments for the given service.
(See Note 1)
[<service>]
CONN_ARGS

<service>_CONN_ARGS
(service-dependent) ””
Specify how much debug information will be output.
(See Note 1)
[<service>]
CONN_DEBUG_PRINTOUT

<service>_CONN_DEBUG_PRINTOUT
CI  a:
to get some: 1, on, yes, true, some
to get all: data, all
to get none: anything else
””
If this parameter is true, the network dispatcher will be disabled.
(See Note 1)
[<service>]
CONN_DISPD_DISABLE

<service>_CONN_DISPD_DISABLE
Boolean  c true
Sets the DTAB (delegation table) for routing via NAMERD.
(See Note 1)
[<service>]
CONN_DTAB

<service>_CONN_DTAB
string ””
If this parameter is true, the Firewall mode will be enabled.
(See Note 1)
[<service>]
CONN_FIREWALL

<service>_CONN_FIREWALL
Boolean  c not set
Set the dispatcher host name.
(See Note 1)
[<service>]
CONN_HOST

<service>_CONN_HOST
a valid host name www.ncbi.nlm.nih.gov
Set the HTTP proxy server.
(See Note 1)
[<service>]
CONN_HTTP_PROXY_HOST

<service>_CONN_HTTP_PROXY_HOST
a valid proxy host ””
Set the HTTP proxy server port number. This will be set to zero if <service>_CONN_HTTP_PROXY_HOST is not set.
(See Note 1)
[<service>]
CONN_HTTP_PROXY_PORT

<service>_CONN_HTTP_PROXY_PORT
unsigned short 0
Set a custom user header. This is rarely used, and then typically for debugging purposes.
(See Note 1)
[<service>]
CONN_HTTP_USER_HEADER

<service>_CONN_HTTP_USER_HEADER
a valid HTTP header ””
Prohibit the use of a local load balancer. Note: This parameter is discouraged for performance reasons - please use <service>_CONN_LBSMD_DISABLE instead.
(See Note 1)
[<service>]
CONN_LB_DISABLE

<service>_CONN_LB_DISABLE
Boolean  c false
Prohibit the use of a local load balancer. This should be used instead of <service>_CONN_LB_DISABLE.
(See Note 1)
[<service>]
CONN_LBSMD_DISABLE

<service>_CONN_LBSMD_DISABLE
Boolean  c false
Enable linkerd-based service name resolution.
(See Note 1)
Note: You must also set <service>_CONN_LBSMD_DISABLE=1 for this to take effect.
[<service>]
CONN_LINKERD_ENABLE

<service>_CONN_LINKERD_ENABLE
Boolean  c false
Enable the use of locally configured services.
See <service>_CONN_LOCAL_SERVER_<n>.
(See Note 1)
[<service>]
CONN_LOCAL_ENABLE

<service>_CONN_LOCAL_ENABLE
Boolean  c false
Create a service entry for service, where n is a number from 0 to 100 (not necessarily sequential). The value must be a valid server descriptor, as it would be configured for the load balancing daemon (LBSMD). This is a quick way of configuring locally used services (usually, for the sole purposes of debugging / development) without the need to edit the actual LBSMD tables (which become visible for the whole NCBI). See <service>_CONN_LOCAL_ENABLE. Note: This parameter has no corresponding global parameter.
(See Note 1)
[<service>]
CONN_LOCAL_SERVER_<n>

<service>_CONN_LOCAL_SERVER_<n>
any non-empty string not set
Maximum number of attempts to establish connection. Zero means use the default.
(See Note 1)
[<service>]
CONN_MAX_TRY

<service>_CONN_MAX_TRY
unsigned short 3
Enable namerd-based service name resolution.
(See Note 1)
(See Note 3)
Note: You must also set <service>_CONN_LBSMD_DISABLE=1 for this to take effect.
[<service>]
CONN_NAMERD_ENABLE

<service>_CONN_NAMERD_ENABLE
Boolean  c false
Enable namerd-based service name resolution specifically for the case when linkerd-based service name resolution has failed (use <service>_CONN_NAMERD_ENABLE to enable namerd-based resolution generally).
(See Note 1)
[<service>]
CONN_NAMERD_FOR_LINKERD_ENABLE

<service>_CONN_NAMERD_FOR_LINKERD_ENABLE
Boolean  c false
Specify a password for the connection (only used with <service>_CONN_USER).
(See Note 1)
[<service>]
CONN_PASS

<service>_CONN_PASS
the user’s password ””
Set the path to the service.
(See Note 1)
[<service>]
CONN_PATH

<service>_CONN_PATH
a valid service path /Service/dispd.cgi
Set the dispatcher port number.
(See Note 1)
[<service>]
CONN_PORT

<service>_CONN_PORT
unsigned short 0
Set a non-transparent CERN-like firewall proxy server.
(See Note 1)
[<service>]
CONN_PROXY_HOST

<service>_CONN_PROXY_HOST
a valid proxy host ””
Set the HTTP request method.
(See Note 1)
[<service>]
CONN_REQ_METHOD

<service>_CONN_REQ_METHOD
CI a: any, get, post ANY
Redirect connections to <service> to the specified alternative service. See Service Redirection.
(See Note 1)
[<service>]
CONN_SERVICE_NAME

<service>_CONN_SERVICE_NAME
a replacement for the service name (none)
Set to true if the client is stateless.
(See Note 1)
[<service>]
CONN_STATELESS

<service>_CONN_STATELESS
Boolean  c false
Zero means no waiting but polling (may not work well with all connections); “infinite” means no timeout (i.e. to wait for I/O indefinitely); other values are the maximum number of seconds to wait before failing.
(See Note 1.)
[<service>]
CONN_TIMEOUT

<service>_CONN_TIMEOUT
floating point >= 0.0 (1 microsecond precision)  f or “infinite” 30.0
Specify a username for the connection (see <service>_CONN_PASS). Only necessary for connections requiring authentication.
(See Note 1)
[<service>]
CONN_USER

<service>_CONN_USER
a username with access rights for the connection (none)
Set the level of logging detail that GNUTLS should produce about secure transactions. Log levels greater than 7 also dump scrambled data from GNUTLS. [CONN]
GNUTLS_LOGLEVEL

CONN_GNUTLS_LOGLEVEL
0 to 10 0
A true value enables HTTP connections to dump headers of error server responses only (successful responses do not get logged). [CONN]
HTTP_ERROR_HEADER_ONLY

CONN_HTTP_ERROR_HEADER_ONLY
Boolean  c false
A true value enables HTTP connections to follow https to http transitions (http to https transitions are secure and therefore don’t need to be enabled). [CONN]
HTTP_UNSAFE_REDIRECTS

CONN_HTTP_UNSAFE_REDIRECTS
Boolean  c false
Set a default referer (applies to all HTTP connections). [CONN]
HTTP_REFERER

CONN_HTTP_REFERER
a valid referer (none)
A list of identifiers to be treated as local services defined in the registry / environment. This parameter is optional and is used only for reverse address-to-name lookups. [CONN]
LOCAL_SERVICES

CONN_LOCAL_SERVICES
whitespace-delimited  d list of identifiers (none)
Set the mail gateway host. [CONN]
MX_HOST

CONN_MX_HOST
a valid host name localhost on Unix platforms except Cygwin; mailgw on all other platforms
Set the mail gateway port. [CONN]
MX_PORT

CONN_MX_PORT
1 to 65535 25 (SMTP)
Set the mail gateway communication timeout in seconds. [CONN]
MX_TIMEOUT

CONN_MX_TIMEOUT
floating point >= 0.0 (zero means default) 120
Use poll(2) instead of select(2) to wait for available data for reading/writing. This is necessary if the number of open file descriptors exceeds 1024. [CONN]
PIPE_USE_POLL

CONN_PIPE_USE_POLL
Boolean  c false
Enable CServer to catch exceptions. [server]
Catch_Unhandled_Exceptions

CSERVER_CATCH_UNHANDLED_EXCEPTIONS
Boolean  b true
Enable CThreadInPool_ForServer to catch exceptions. [ThreadPool]
Catch_Unhandled_Exceptions

NCBI_CONFIG__THREADPOOL__CATCH_UNHANDLED_EXCEPTIONS  e
Boolean  b true

a CI = case-insensitive

b case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

c case-insensitive: true values are { 1, on, yes, true }; false is anything else

d whitespace can be any number of spaces and/or tabs

e environment variable name formed from registry section and entry name

f although very precise values may be specified, practical host limitations my result in less precise effective values

Note 1: All service-specific parameters shown in Table 7 (except one) have corresponding global parameters - i.e. parameters that apply to all services. For these global parameters, the registry section name is CONN; the registry entry name doesn’t have the CONN_ prefix; and the environment variable doesn’t have the <service>_ prefix. For example, the service-specific parameter specified by the CONN_ARGS entry in a given [<service>] section of the registry (or by the <service>_CONN_ARGS environment variable) corresponds to the global parameter specified by the ARGS entry in the [CONN] section of the registry (or by the CONN_ARGS environment variable). When both a service-specific parameter and its corresponding global parameter are set, the service-specific parameter takes precedence.

Note 2: Environment variable names for service-specific parameters are formed by capitalizing the service name.

Note 3: See Dispatching with namerd and Linkerd for additional namerd-related configuration parameters not typically needed by end users.

CGI and FCGI

The folowing sections show parameters that tune CGI and FCGI applications and CGI load balancing.

CGI

These parameters tune the behavior of CGI applications.

Table 8. CGI-related configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Set to the user agent string you would like to be used by the web server. [N/A]
N/A

HTTP_USER_AGENT
A valid user agent string. (none)
Allow SIGPIPE in a plain (non-FastCGI) C++ Toolkit CGI (i.e. CCgiApplication-derived). [CGI]
Allow_Sigpipe

CGI_ALLOW_SIGPIPE
Boolean  c false
Add to the user agent list of bot names. This parameter affect only CCgiUserAgent::IsBot(). [CGI]
Bots

NCBI_CONFIG__CGI__BOTS  f
Delimited list  b of bot names, e.g. “Googlebot Scooter WebCrawler Slurp”. (none)
When true (and when using HTTP/1.1), produce the CGI response in chunks, with the size set by [CGI].ChunkSize. [CGI]
ChunkedTransfer

CGI_CHUNKED_TRANSFER
“Disable” or “Enable” “Disable”
Set the size of the chunks when producing chunked CGI responses per [CGI].ChunkedTransfer. [CGI]
ChunkSize

CGI_CHUNK_SIZE
positive integer 4096
According to RFC-2109, cookies should not be encoded. Instead, they should be just quoted. However, for backward compatibility with code that decodes incoming cookies, both quoted cookies and encoded cookies can be parsed. This setting controls which method of encoding/decoding is used. [CGI]
Cookie_Encoding

CGI_COOKIE_ENCODING
“Url”, “Quote” “Url”
Severity level for cookie-related error messages. [CGI]
Cookie_Error_Severity

CGI_Cookie_Error_Severity
CI  e: Info, Warning, Error, Critical, Fatal, Trace Error
Defines which characters cannot be used in cookie names. [CGI]
Cookie_Name_Banned_Symbols

CGI_Cookie_Name_Banned_Symbols
A string of banned characters. ”  ,;=”
See CGI_CORS_Enable. Specify the value of the Access-Control-Allow-Credentials header, which indicates whether or not the response to the request can be exposed when the credentials flag is true.  g [CGI]
CORS_Allow_Credentials

CGI_CORS_ALLOW_CREDENTIALS
either do not set, or use the string “true” (not set)
See CGI_CORS_Enable. Specify the value of the Access-Control-Allow-Headers header, which is used in response to a preflight request to indicate which HTTP headers can be used when making the actual request.  g [CGI]
CORS_Allow_Headers

CGI_CORS_ALLOW_HEADERS
string “X-Requested-With”
See CGI_CORS_Enable. Specify the value of the Access-Control-Allow-Methods header, which specifies the method or methods allowed when accessing the resource (in response to a preflight request).  g [CGI]
CORS_Allow_Methods

CGI_CORS_ALLOW_METHODS
string “GET, POST, OPTIONS”
See CGI_CORS_Enable. Specify the value of the Access-Control-Allow-Origin header. Should be a space-separated list of domain suffixes (e.g. ‘foo.com bar.org’) that are permitted to access the resource. The Origin header sent by the client is matched against the list. If there’s no match, CORS is not enabled. If matched, the client provided Origin is copied to the outgoing Access-Control-Allow-Origin. To allow any origin set the value to ‘*’ (this should be a single character, not part of the list). [CGI]
CORS_Allow_Origin

CGI_CORS_ALLOW_ORIGIN
string - either “*” or a valid origin “ncbi.nlm.nih.gov”
Set to true to enable Cross-Origin Resource Sharing (CORS), and use non-empty parameters for given headers (e.g. CORS_Allow_Origin etc) to set the value for those headers. If false or not set, cross-origin request headers will cause an error. [CGI]
CORS_Enable

CGI_CORS_Enable
Boolean  c false
See CGI_CORS_Enable. Specify the value of the Access-Control-Expose-Headers header, which lets a server whitelist headers that browsers are allowed to access.  g [CGI]
CORS_Expose_Headers

CGI_CORS_EXPOSE_HEADERS
string ””
See CGI_CORS_Enable. Param to enable JQuery JSONP hack to allow Cross-Origin Resource Sharing for browsers that don’t support CORS (e.g. IE versions earlier than 11). If it is set to true and the HTTP request contains entry “callback” whose value starts with “JQuery_” (case-insensitive, configurable - see CGI_CORS_JQUERY_CALLBACK_PREFIX), then:
1. Set the response Content-Type to “text/javascript”; and
2. Wrap the response content into: “JQuery_foobar(original_content)”
[CGI]
CORS_JQuery_Callback_Enable

CGI_CORS_JQUERY_CALLBACK_ENABLE
Boolean  c false
See CGI_CORS_Enable. Specify a prefix other than “JQuery_” for the JQuery JSONP callback name (see CGI_CORS_JQUERY_CALLBACK_ENABLE). Use the symbol ‘*’ if any name is good. [CGI]
CORS_JQuery_Callback_Prefix

CGI_CORS_JQUERY_CALLBACK_PREFIX
string ”*”
See CGI_CORS_Enable. Specify the value of the Access-Control-Max-Age header, which indicates how long the results of a preflight request can be cached.  g [CGI]
CORS_Max_Age

CGI_CORS_MAX_AGE
string (seconds) ””
Set to true to make the application count the amount of data read/sent. The numbers are then printed in request stop log messages. [CGI]
Count_Transfered

CGI_COUNT_TRANSFERED
Boolean  c true
Set the name of an environment variable, which in turn specifies a prefix that will be added to all diagnostic messages issued during HTTP request processing. [CGI]
DiagPrefixEnv

NCBI_CONFIG__CGI__DIAGPREFIXENV  f
a valid environment variable name (none)
When true, discard the session tracking ID if it’s set to “UNK_SESSION”. For example, if “UNK_SESSION” is set through HTTP_NCBI_SID (which would generally be a bad practice), this will result in it being replaced with a valid SID. [CGI]
Discard_UNK_SESSION

NCBI_CGI_DISCARD_UNK_SESSION
Boolean c false
When true, and when the request method is GET and the ncbi_help[=format] URL parameter is passed, return a help message to the CGI client. The following sources are checked in the given order for the help message content (all sources except the last are files located with the CGI):
<cginame>.help.<format>
help.<format>
<cginame>.help.<accept_hdr_subtype><accept_hdr_mediarangeparams>
help.<accept_hdr_subtype><accept_hdr_mediarangeparams>
<cginame>.help.html
<cginame>.help.xml
<cginame>.help.json
help.html
help.xml
help.json
• an XML representation of the result of GetArgDescriptions()
[CGI]
EnableHelpRequest

CGI_ENABLE_HELP_REQUEST
Boolean  c true
When the request method is “GET” and the [CGI].EnableVersionRequest configuration parameter is true and the ncbi_version URL parameter is supplied and empty or “short” or “full”, then the CGI application version is returned to the CGI client. Alternatively, the [CGI].EnableVersionRequest configuration parameter can name a URL parameter that will substitute for ncbi_version. In both cases, the short version is returned unless “full” is specified.
By default, the version is returned as content type “text/plain”, but this can be overridden by supplying either “xml” or “json” as the subtype in an Accept header.
A non-empty ncbi_version (or overridden URL parameter) with a value other than “short” or “full” will result in an error, as will an Accept header subtype other than “xml” or “json”.
[CGI]
EnableVersionRequest

CGI_ENABLE_VERSION_REQUEST
either Boolean c or the name of a URL parameter false
This parameter applies only to HEAD requests:

If false, no exception is thrown and the application continues to run, but the output stream is blocked so that no more data can be sent to the client. If any attempts are made to write response content after the headers have been written, then an error will be posted to the log (but only the first time).

If true, the CGI application framework will throw CCgiHeadException after writing the headers. Note: This exception must percolate up to CCgiApplication::Run() for this option to work correctly, typically by catching and rethrowing it in ProcessRequest(). In this case the application will exit immediately after writing the headers with HTTP status code 200.
[CGI]
ExceptionAfterHEAD

NCBI_CONFIG__CGI__EXCEPTIONAFTERHEAD  f
Boolean  c false
Set to true to disable the creation of a tracking cookie during session initialization. [CGI]
DisableTrackingCookie

NCBI_CONFIG__CGI__DISABLETRACKINGCOOKIE  f
Boolean  c false
Set to true to enable logging. [CGI]
Log

NCBI_CONFIG__CGI__LOG  f
CI  e:
On => enabled;
True => enabled;
OnError => enabled for errors;
OnDebug => enabled (debug builds only)
disabled
An ampersand-delimited string of GET and/or POST arguments to exclude from the log (helps limit the size of the log file) [CGI]
LOG_EXCLUDE_ARGS

CGI_LOG_EXCLUDE_ARGS
valid format: arg1&arg2… (none)
Allows specifying limits for multiple GET and/or POST arguments in one parameter string. [CGI]
LOG_LIMIT_ARGS

CGI_LOG_LIMIT_ARGS
valid format: arg1:size1&arg2:size2…&*:size
special argument:
* means all unspecified arguments;
special limits:
-2 means exclude;
-1 means no limit
*:1000000
Enable logging of CGI request parameters. Only the specified parameters will be logged. [CGI]
LogArgs

NCBI_CONFIG__CGI__LOGARGS  f
Delimited list  a of environment variables (optionally aliased on output for shortening logs, e.g. envvar=1). (none)
Set to true to merge log lines. [CGI]
Merge_Log_Lines

CGI_MERGE_LOG_LINES
Boolean  c true
Specify additional mobile device names. This parameter affect only CCgiUserAgent::IsMobileDevice(). [CGI]
MobileDevices

NCBI_CONFIG__CGI__MobileDevices  f
Delimited list  b of additional device names. (none)
Add to the user agent list of names that aren’t bots. This parameter affect only CCgiUserAgent::IsBot(). [CGI]
NotBots

NCBI_CONFIG__CGI__NotBots  f
Delimited list  b of names that aren’t bots. (none)
Add to the user agent list of names that aren’t mobile devices. This parameter affect only CCgiUserAgent::IsMobileDevice(). [CGI]
NotMobileDevices

NCBI_CONFIG__CGI__NotMobileDevices  f
Delimited list  b of names that aren’t mobile devices. (none)
Add to the user agent list of names that aren’t phone devices. This parameter affect only CCgiUserAgent::IsPhoneDevice(). [CGI]
NotPhoneDevices

NCBI_CONFIG__CGI__NotPhoneDevices  f
Delimited list  b of names that aren’t phone devices. (none)
Add to the user agent list of names that aren’t tablet devices. This parameter affect only CCgiUserAgent::IsTabletDevice(). [CGI]
NotTabletDevices

NCBI_CONFIG__CGI__NotTabletDevices  f
Delimited list  b of names that aren’t tablet devices. (none)
Control error handling of incoming cookies (doesn’t affect outgoing cookies set by application). [CGI]
On_Bad_Cookie

CGI_ON_BAD_COOKIE
CI  e: Throw, SkipAndError, Skip, StoreAndError, Store Store
Specify additional phone device names. This parameter affect only CCgiUserAgent::IsPhoneDevice(). [CGI]
PhoneDevices

NCBI_CONFIG__CGI__PhoneDevices  f
Delimited list  b of additional device names. (none)
Specifies whether to print the referer during LogRequest(). [CGI]
Print_Http_Referer

CGI_PRINT_HTTP_REFERER
Boolean  c true
Specifies whether to print the URL during LogRequest(). [CGI]
Print_Self_Url

CGI_PRINT_SELF_URL
Boolean  c true
Specifies whether to print the user agent during LogRequest(). [CGI]
Print_User_Agent

CGI_PRINT_USER_AGENT
Boolean  c true
Set the size of CGI request buffer that is printed when the request cannot be parsed. [CGI]
RequestErrBufSize

NCBI_CONFIG__CGI__REQUESTERRBUFSIZE  f
buffer size in bytes 256
Specify the registry section name for the result cache. [CGI]
ResultCacheSectionName

NCBI_CONFIG__CGI__RESULTCACHESECTIONNAME  f
valid section name result_cache
Enable statistics logging. [CGI]
StatLog

NCBI_CONFIG__CGI__STATLOG  f
Boolean  d false
Specify additional tablet device names. This parameter affect only CCgiUserAgent::IsTabletDevice(). [CGI]
TabletDevices

NCBI_CONFIG__CGI__TabletDevices  f
Delimited list  b of additional device names. (none)
Controls whether the output stream will throw for bad states. [CGI]
ThrowOnBadOutput

NCBI_CONFIG__CGI__THROWONBADOUTPUT  f
Boolean  c true
Log start time, end time, and elapsed time. [CGI]
TimeStamp

NCBI_CONFIG__CGI__TIMESTAMP  f
Boolean  d false
Disable statistics logging if the CGI request took less than the specified number of seconds. [CGI]
TimeStatCutOff

NCBI_CONFIG__CGI__TIMESTATCUTOFF  f
non-negative integer (zero enables logging) 0
Specify the domain for the tracking cookie. [CGI]
TrackingCookieDomain

NCBI_CONFIG__CGI__TRACKINGCOOKIEDOMAIN  f
valid domain .nih.gov
Specify the tracking cookie name. [CGI]
TrackingCookieName

NCBI_CONFIG__CGI__TRACKINGCOOKIENAME  f
valid cookie name ncbi_sid
Specify the path for the tracking cookie. [CGI]
TrackingCookiePath

NCBI_CONFIG__CGI__TRACKINGCOOKIEPATH  f
valid path /
Defines the name of the NCBI tracking cookie (session ID cookie). [CGI]
TrackingTagName

CGI_TrackingTagName
Any valid cookie name. “NCBI-SID”
Specify a set of fields (e.g. HTTP headers when the protocol is HTTP) to be taken from incoming requests and passed to outgoing requests.
For more details, see the NCBI Context Fields Confluence page.
[Context]
Fields

NCBI_CONTEXT_FIELDS
A space-delimited, case-insensitive list of glob patterns. ””

a List may be delimited by semicolon, space, tab, or comma.

b List may be delimited by newlines or any of the special characters: semicolon, space, tab, vertical bar, or tilde. If the list contains one or more newlines then only newlines will be used as delimiters and the values in the list will be the content of the lines including any special characters. If the list does not contain any newline characters then all special characters will act as independent delimiters. Therefore, if any value in the list needs to include any of the special characters, then newlines must be used as the delimiter.

c case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

d case-insensitive: true, t, yes, y, false, f, no, n

e CI = case-insensitive

f environment variable name formed from registry section and entry name

g some information from HTTP access control (CORS) by Mozilla Contributors, adapted under CC-BY-SA

FCGI

These parameters tune the behavior of FCGI applications.

Table 9. FCGI-related configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
A true value enables logging of current iteration, max iterations, and process ID during the FastCGI run. [FastCGI]
Debug

NCBI_CONFIG__FASTCGI__DEBUG  b
Boolean  a false
A true value enables termination of a FastCGI application by the presence of the request entry “exitfastcgi”. [FastCGI]
HonorExitRequest

NCBI_CONFIG__FASTCGI__HONOREXITREQUEST  b
Boolean  a false
Specify the number of requests that the FCGI application will process before exiting. [FastCGI]
Iterations

NCBI_CONFIG__FASTCGI__ITERATIONS  b
positive integer 10
Make the FastCGI application run as a stand-alone server on a local port. The value is a Unix domain socket or a MS Windows named pipe, or a colon followed by a port number [FastCGI]
StandaloneServer

FCGI_STANDALONE_SERVER
valid local port or named socket (none)
Make the FastCGI application stop if an error is encountered. [FastCGI]
StopIfFailed

NCBI_CONFIG__FASTCGI__STOPIFFAILED  b
Boolean  a false
Make the FastCGI application stop if the memory limit is exceeded. [FastCGI]
TotalMemoryLimit

NCBI_CONFIG__FASTCGI__TOTALMEMORYLIMIT
An optionally suffixed non-negative real number (e.g. “123456789”, “100MiB”, or “1.25 G”).

No suffix (or a “B” suffix) means the given value is in bytes.

If there is a suffix, there can be spaces between the number and the suffix. The default units are decimal (i.e. powers of 1000) - e.g. “MB”. The final “B” is optional for decimal units (e.g. “M”). You can use “i” to indicate binary units (i.e. powers of 1024) – e.g. “MiB”.

Valid suffix characters are: “K”, “M”, “G”, “T”, “P”, and “E”.

Suffixes are not case-sensitive.
0 (unlimited)
Make the FastCGI application exit if the named file changes. [FastCGI]
WatchFile.Name

NCBI_CONFIG__FASTCGI__WATCHFILE_DOT_NAME  b
valid file name (none)
The number of bytes to read from the watch file to see if it has changed. [FastCGI]
WatchFile.Limit

NCBI_CONFIG__FASTCGI__WATCHFILE_DOT_LIMIT  b
positive integer (non-positives trigger default) 1024
The period in seconds between checking the watch file for changes. [FastCGI]
WatchFile.Timeout

NCBI_CONFIG__FASTCGI__WATCHFILE_DOT_TIMEOUT  b
positive integer (non-positives trigger default, which is to disable the watch file checking) 0

a case-insensitive: true, t, yes, y, false, f, no, n

b environment variable name formed from registry section and entry name

CGI Load Balancing

These parameters tune the CGI load balancer.

Table 10. CGI load balancing configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Specify the internet domain. [CGI-LB]
Domain

NCBI_CONFIG__CGI-LB__DOMAIN  b
a valid domain .ncbi.nlm.nih.gov
Specify the host IP address. [CGI-LB]
Host

NCBI_CONFIG__CGI-LB__HOST  b
a valid host IP (none)
Specify the cookie expiration period in seconds. [CGI-LB]
LifeSpan

NCBI_CONFIG__CGI-LB__LIFESPAN  b
integer 0
Specify the name of the load balancing cookie in the HTTP response. [CGI-LB]
Name

NCBI_CONFIG__CGI-LB__NAME  b
a valid cookie name (none)
Specify the cookie path. [CGI-LB]
Path

NCBI_CONFIG__CGI-LB__PATH  b
a valid path (none)
Specify the cookie security mode. [CGI-LB]
Secure

NCBI_CONFIG__CGI-LB__SECURE  b
Boolean  a false

a case-insensitive: true, t, yes, y, false, f, no, n

b environment variable name formed from registry section and entry name

Serial

These parameters tune the behavior of the Serial library.

Table 11. Serial library configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Skip unknown data members in the input stream, or throw an exception. [N/A]
N/A

SERIAL_SKIP_UNKNOWN_MEMBERS
CI  a: yes, no, never, always no (throw)
If true, causes CObjectOStream::WriteDouble() to use fast conversion. [SERIAL]
FastWriteDouble

NCBI_CONFIG__SERIAL__FastWriteDouble  b
Boolean  c true
While reading binary ASN.1 data allow VisibleString tag where UTF-8 string tag is expected by specification. [SERIAL]
READ_ANY_UTF8STRING_TAG

SERIAL_READ_ANY_UTF8STRING_TAG
Boolean  c true
While reading binary ASN.1 data allow UTF-8 string tag where VisibleString tag is expected by specification. [SERIAL]
READ_ANY_VISIBLESTRING_TAG

SERIAL_READ_ANY_VISIBLESTRING_TAG
0 (disallow, throws an exception);
1 (allow, but warn once);
2 (allow without warning)
1
If true, use memory-mapped file access, which associates a file’s content with a portion of the virtual address space of a process. This can result in a modest performance increase (probably < 15%). [SERIAL]
READ_MMAPBYTESOURCE

SERIAL_READ_MMAPBYTESOURCE
Boolean  c false
Specify how to handle unknown variants when reading Object streams. [SERIAL]
SKIP_UNKNOWN_MEMBERS

NCBI_CONFIG__SERIAL__SKIP_UNKNOWN_MEMBERS  b
CI  a:
no (throw an exception),
never (even if set to skip later),
yes (skip),
always (even if set to not skip later)
no
Specify how to handle unknown variants when reading Object streams. [SERIAL]
SKIP_UNKNOWN_VARIANTS

NCBI_CONFIG__SERIAL__SKIP_UNKNOWN_VARIANTS  b
CI  a:
no (throw an exception),
never (even if set to skip later),
yes (skip),
always (even if set to not skip later)
no
Throw an exception on an attempt to access an uninitialized data member. [SERIAL]
VERIFY_DATA_GET

SERIAL_VERIFY_DATA_GET
CI  a: yes, no, never, always, defvalue, defvalue_always yes
Throw an exception if a mandatory data member is missing in the input stream. [SERIAL]
VERIFY_DATA_READ

SERIAL_VERIFY_DATA_READ
CI  a: yes, no, never, always, defvalue, defvalue_always yes
Throw an exception on an attempt to write an uninitialized data member. [SERIAL]
VERIFY_DATA_WRITE

SERIAL_VERIFY_DATA_WRITE
CI  a: yes, no, never, always, defvalue, defvalue_always yes
While writing binary ASN.1 data issue UTF8 string tag as determined by specification, otherwise issue plain string tag. [SERIAL]
WRITE_UTF8STRING_TAG

SERIAL_WRITE_UTF8STRING_TAG
Boolean  c false
Specifies what to do if an invalid character is read. [SERIAL]
WRONG_CHARS_READ

NCBI_CONFIG__SERIAL__WRONG_CHARS_READ  b
“ALLOW”,
“REPLACE”,
“REPLACE_AND_WARN”,
“THROW”,
“ABORT”
“REPLACE_AND_WARN”
Specifies what to do if an invalid character is written. [SERIAL]
WRONG_CHARS_WRITE

NCBI_CONFIG__SERIAL__WRONG_CHARS_WRITE  b
“ALLOW”,
“REPLACE”,
“REPLACE_AND_WARN”,
“THROW”,
“ABORT”
“REPLACE_AND_WARN”

a CI = case-insensitive

b environment variable name formed from registry section and entry name

c case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

Objects, Object Manager, Object Tools

These parameters tune the behavior of the Objects-related libraries, including the Object Manager and loader and reader libraries.

Table 13. Objects-related configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Specify whether the blob stream processor should try to use string packing. [N/A]
N/A

NCBI_SERIAL_PACK_STRINGS
Boolean  d true
The Object Manager will attach WGS master descriptors to Bioseq data by default. Setting this parameter to false will disable this behavior. [GENBANK]
ADD_WGS_MASTER

GENBANK_ADD_WGS_MASTER
Boolean  a true
A non-zero value turns on debugging messages about GenBank loader’s interaction with cache. [GENBANK]
CACHE_DEBUG

GENBANK_CACHE_DEBUG
>=0, currently only zero and non-zero are distinguished 0
Specify whether an attempt should be made to recompress the cache. [GENBANK]
CACHE_RECOMPRESS

GENBANK_CACHE_RECOMPRESS
Boolean  a true
A non-zero value turns on debugging messages about opening/closing connections to ID1/ID2 services. [GENBANK]
CONN_DEBUG

GENBANK_CONN_DEBUG
>=0, currently only zero and non-zero are distinguished 0
Disable attaching WGS master descriptors when retrieving ASN.1 blobs using the CPubseqReader class. [GENBANK/PUBSEQOS]
EXCLUDE_WGS_MASTER

NCBI_CONFIG__GENBANK_PUBSEQOS__EXCLUDE_WGS_MASTER
Boolean  b false
Disable attaching WGS master descriptors when retrieving ASN.1 blobs using the CPubseq2Reader class. [GENBANK/PUBSEQOS2]
EXCLUDE_WGS_MASTER

NCBI_CONFIG__GENBANK_PUBSEQOS2__EXCLUDE_WGS_MASTER
Boolean  b false
Set the severity level for ID1 debug tracing. [GENBANK]
ID1_DEBUG

GENBANK_ID1_DEBUG
int:
0 = none,
1 = error,
2 = open,
4 = conn,
5 = asn,
8 = asn data
0
Specify the ID1 reader service name. Note: The services can be redirected using generic Service Redirection technique. Has precedence over [NCBI].SERVICE_NAME_ID1 [GENBANK]
ID1_SERVICE_NAME

GENBANK_ID1_SERVICE_NAME
a valid reader service name ID1
(see API)
Specify the ID2 reader service name. Note: The services can be redirected using generic Service Redirection technique. Has precedence over [GENBANK].ID2_SERVICE_NAME [GENBANK]
ID2_CGI_NAME

GENBANK_ID2_CGI_NAME
a valid reader service name ID2
(see API)
Set the severity level for ID2 debug tracing. [GENBANK]
ID2_DEBUG

GENBANK_ID2_DEBUG
int:
0 = none,
1 = error,
2 = open,
4 = conn,
5 = asn,
8 = blob,
9 = blob data
debug: none
release: error
(see API)
Number of chunks allowed in a single request. [GENBANK]
ID2_MAX_CHUNKS_REQUEST_SIZE

GENBANK_ID2_MAX_CHUNKS_REQUEST_SIZE
int:
0 = unlimited request size;
1 = do not use packets or get-chunks requests
100
Maximum number of requests packed in a single ID2 packet. [GENBANK]
ID2_MAX_IDS_REQUEST_SIZE

GENBANK_ID2_MAX_IDS_REQUEST_SIZE
>=0 100
Specify the ID2 reader service name. Note: The services can be redirected using generic Service Redirection technique. Has precedence over [NCBI].SERVICE_NAME_ID2 [GENBANK]
ID2_SERVICE_NAME

GENBANK_ID2_SERVICE_NAME
a valid reader service name ID2
(see API)
Prioritized list of drivers to try for the reader or writer.
Less precedence than [GENBANK].READER_NAME or [GENBANK].WRITER_NAME.
[GENBANK]
LOADER_METHOD

GENBANK_LOADER_METHOD
list items are semicolon-delimited;
each item is a colon-delimited list of drivers.
valid drivers:
id1, id2, cache, pubseqos
#if defined(HAVE_PUBSEQ_OS)
“ID2:PUBSEQOS:ID1”
else
“ID2:ID1”
#endif
(see API)
The maximum number of connections the reader can establish to the data source. This is run-time limited to 1 for single threaded clients and for all clients using the cache or gi reader, and to 5 for multi-threaded clients using the id1, id2, pubseqos, and pubseqos2 readers. [GENBANK]
MAX_NUMBER_OF_CONNECTIONS
int 3 for id1 and id2; 2 for pubseqos and pubseqos2
See MAX_NUMBER_OF_CONNECTIONS [GENBANK]
NO_CONN
   
See OPEN_TIMEOUT_INCREMENT [GENBANK]
OPEN_INCREMENT
   
See OPEN_TIMEOUT_MAX [GENBANK]
OPEN_MAX
   
See OPEN_TIMEOUT_MULTIPLIER [GENBANK]
OPEN_MULTIPLIER
   
The OPEN_TIMEOUT* parameters describe the timeout for opening a GenBank connection. The timeout allows the server a reasonable time to respond while providing a means to quickly abandon unresponsive servers. [GENBANK]
OPEN_TIMEOUT

NCBI_CONFIG__GENBANK__OPEN_TIMEOUT  c
any floating point value >= 0.0 5 seconds
OPEN_TIMEOUT_MULTIPLIER and OPEN_TIMEOUT_INCREMENT specify the way the open timeout is increased if no response is received (next_open_timeout = prev_open_timeout * multiplier + increment). [GENBANK]
OPEN_TIMEOUT_INCREMENT

NCBI_CONFIG__GENBANK__OPEN_TIMEOUT_INCREMENT  c
any floating point value >= 0.0 0 seconds
The limit of increasing the open timeout using OPEN_TIMEOUT_MULTIPLIER and OPEN_TIMEOUT_INCREMENT. [GENBANK]
OPEN_TIMEOUT_MAX

NCBI_CONFIG__GENBANK__OPEN_TIMEOUT_MAX  c
floating point >= 0.0 30 seconds
See OPEN_TIMEOUT_INCREMENT [GENBANK]
OPEN_TIMEOUT_MULTIPLIER

NCBI_CONFIG__GENBANK__OPEN_TIMEOUT_MULTIPLIER  c
floating point >= 0.0 1.5
Whether to open first connection immediately or not. [GENBANK]
preopen

NCBI_CONFIG__GENBANK__PREOPEN  c
Boolean  b true
Turns on different levels of debug messages in PubSeqOS reader. A value >=2 means debug opening connections while >=5 means debug results of Seq-id resolution requests. Note: only applies to debug builds. [GENBANK]
PUBSEQOS_DEBUG

GENBANK_PUBSEQOS_DEBUG
int 0
Prioritized list of drivers to try for the reader. Has precedence over [GENBANK].LOADER_METHOD. [GENBANK]
READER_NAME

GENBANK_READER_NAME
See [GENBANK].LOADER_METHOD. See [GENBANK].LOADER_METHOD.
Specify the level of reader statistics to collect. [GENBANK]
READER_STATS

GENBANK_READER_STATS
int:
0 = none,
1 = verbose
0
Specify whether the reader manager should automatically register ID1, ID2, and cache. [GENBANK]
REGISTER_READERS

GENBANK_REGISTER_READERS
Boolean  a true
On some platforms, equal strings can share their character data, reducing the required memory. Set this parameter to true to have the GenBank loader try to use this feature if it is available. [GENBANK]
SNP_PACK_STRINGS

GENBANK_SNP_PACK_STRINGS
Boolean  a true
In ID1/PubSeqOS readers present SNP data as ID2-split entries to reduce memory usage. [GENBANK]
SNP_SPLIT

GENBANK_SNP_SPLIT
Boolean  a true
Storing all the SNPs as plain ASN.1 objects would require a huge amount of memory. The SNP table is a compact way of storing SNPs to reduce memory consumption. Set this parameter to true to have the object manager try to use the SNP table. [GENBANK]
SNP_TABLE

GENBANK_SNP_TABLE
Boolean  a true
Set to a positive integer to enable dumping (to stderr in text ASN.1 form) all the SNPs that don’t fit into the SNP table. Note: this is only available in debug mode. [GENBANK]
SNP_TABLE_DUMP

GENBANK_SNP_TABLE_DUMP
Boolean  a false
Set this parameter to true to dump (to stdout) some statistics on the process of storing SNPs into the SNP table. This option may help determine why not all the SNPs could fit in the table. [GENBANK]
SNP_TABLE_STAT

GENBANK_SNP_TABLE_STAT
Boolean  a false
Specify whether to use a memory pool. [GENBANK]
USE_MEMORY_POOL

GENBANK_USE_MEMORY_POOL
Boolean  a true
The WAIT_TIME* parameters describe the wait time before opening new GenBank connections in case of communication errors. The wait time is necessary to allow network and/or GenBank servers to recover. WAIT_TIME is the initial wait after the first error. See also: GenBank reader configuration. [GENBANK]
WAIT_TIME

NCBI_CONFIG__GENBANK__WAIT_TIME  c
floating point >= 0.0 1 second
Specifies for how many sequential communication errors the response should be to use wait time, before trying to open a new connection instead. [GENBANK]
WAIT_TIME_ERRORS

NCBI_CONFIG__GENBANK__WAIT_TIME_ERRORS  c
int 2 errors
WAIT_TIME_MULTIPLIER and WAIT_TIME_INCREMENT specify the way wait time is increased if errors continue to happen (next_wait_time = prev_wait_time * multiplier + increment). [GENBANK]
WAIT_TIME_INCREMENT

NCBI_CONFIG__GENBANK__WAIT_TIME_INCREMENT  c
any floating point value >= 0.0 1 second
The limit of increasing wait time using WAIT_TIME_MULTIPLIER and WAIT_TIME_INCREMENT. [GENBANK]
WAIT_TIME_MAX

NCBI_CONFIG__GENBANK__WAIT_TIME_MAX  c
floating point >= 0.0 30 seconds
See WAIT_TIME_INCREMENT [GENBANK]
WAIT_TIME_MULTIPLIER

NCBI_CONFIG__GENBANK__WAIT_TIME_MULTIPLIER  c
any floating point value >= 0.0 1.5
Prioritized list of drivers to try for the writer. Has precedence over [GENBANK].LOADER_METHOD. [GENBANK]
WRITER_NAME

GENBANK_WRITER_NAME
See [GENBANK].LOADER_METHOD. See [GENBANK].LOADER_METHOD.
Database lock control. By default LDS2 databases are read-only, so they are cached in memory. If an explicit mode is set in the code, this config parameter is ignored. Note: To set locks the database must be writable. [LDS2]
DataLoader_Lock

LDS2_DATALOADER_LOCK
“lock”, “nolock”, or “cache” “cache”
If true, replace ranges that cannot be mapped with a NULL location instead of using the neighbor’s fuzz. [Mapper]
NonMapping_As_Null

MAPPER_NONMAPPING_AS_NULL
Boolean  a false
Specify the ID1 reader service name. Note: The services can be redirected using generic Service Redirection technique. Less precedence than [GENBANK].ID1_SERVICE_NAME. [NCBI]
SERVICE_NAME_ID1

GENBANK_SERVICE_NAME_ID1
a valid reader service name ID1
(see API)
Specify the ID2 reader service name. Note: The services can be redirected using generic Service Redirection technique. Less precedence than [GENBANK].ID2_SERVICE_NAME. [NCBI]
SERVICE_NAME_ID2

GENBANK_SERVICE_NAME_ID2
a valid reader service name ID2
(see API)
If non-zero, reserve Dense-seg vectors using predefined pre-read hook. [OBJECTS]
DENSE_SEG_RESERVE

OBJECTS_DENSE_SEG_RESERVE
Boolean  a true
Specify whether Seq-id general trees are packed. [OBJECTS]
PACK_GENERAL

OBJECTS_PACK_GENERAL
Boolean  a true
Specify whether Seq-id text-seq trees are packed. [OBJECTS]
PACK_TEXTID

OBJECTS_PACK_TEXTID
Boolean  a true
Specify whether empty Seq-descr’s will be allowed (or throw if not). [OBJECTS]
SEQ_DESCR_ALLOW_EMPTY

OBJECTS_SEQ_DESCR_ALLOW_EMPTY
Boolean  a false
If non-zero, reserve Seq-graph vectors using predefined pre-read hook. [OBJECTS]
SEQ_GRAPH_RESERVE

OBJECTS_SEQ_GRAPH_RESERVE
Boolean  a true
If non-zero, reserve Seq-table vectors using predefined pre-read hook. [OBJECTS]
SEQ_TABLE_RESERVE

OBJECTS_SEQ_TABLE_RESERVE
Boolean  a true
Sets the maximum number of master TSE blobs that will be cached. [OBJMGR]
BLOB_CACHE

OBJMGR_BLOB_CACHE
unsigned int 10
Specify whether the scope can be auto-released. [OBJMGR]
SCOPE_AUTORELEASE

OBJMGR_SCOPE_AUTORELEASE
Boolean  a true
Specify the size of the scope auto-release. [OBJMGR]
SCOPE_AUTORELEASE_SIZE

OBJMGR_SCOPE_AUTORELEASE_SIZE
unsigned int 10
Specify whether the new FASTA implementation will be used. [READ_FASTA]
USE_NEW_IMPLEMENTATION

NCBI_CONFIG__READ_FASTA__USE_NEW_IMPLEMENTATION  c
Boolean  a true
If true, try to avoid GIs where possible, even if there’s no accessions to prefer. [SeqId]
AvoidGi

SEQ_ID_AVOID_GI
Boolean  a false
If true, give GIs worse (higher) score to prefer accessions in CSeq_id ranking methods. [SeqId]
PreferAccessionOverGi

SEQ_ID_PREFER_ACCESSION_OVER_GI
Boolean  a false

a case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

b case-insensitive: true, t, yes, y, false, f, no, n

c environment variable name formed from registry section and entry name

d case-insensitive: true values are { yes | 1 }; anything else is false

cSRA

sraread library

Note: This section applies only inside NCBI.

The following parameters tune the behavior of the sraread library:

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
If true, will add CIGAR info to Seq-align’s returned by cSRA iterators. [csra]
cigar_in_align_ext

CSRA_CIGAR_IN_ALIGN_EXT
Boolean true
If true, will clip the read ranges returned by cSRA short read iterators according to quality. [csra]
clip_by_quality

CSRA_CLIP_BY_QUALITY
Boolean true
If true, will add mate info to Seq-align’s returned by cSRA iterators. [csra]
explicit_mate_info

CSRA_EXPLICIT_MATE_INFO
Boolean false
If true, cSRA short read iterators will also include technical reads. [csra]
include_technical_reads

CSRA_INCLUDE_TECHNICAL_READS
Boolean true

ncbi_xloader_csra library

Note: This section applies only inside NCBI.

The following parameters tune the behavior of the ncbi_xloader_csra library:

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
If >= 9, log alignment chunks.
If >= 5, log major function calls.
If >= 2, log refseq stats.
If >= 1, log summary data.
[csra_loader]
debug

CSRA_LOADER_DEBUG
int 0
The max number of SRR files to keep open. [csra_loader]
gc_size

CSRA_LOADER_GC_SIZE
size_t 10
If > 0, defines the max number of separate spot groups. [csra_loader]
max_separate_spot_groups

CSRA_LOADER_MAX_SEPARATE_SPOT_GROUPS
int 0
If > 0, defines the minimum quality threshold for loading alignment and pileup chunks. [csra_loader]
pileup_graphs

CSRA_LOADER_PILEUP_GRAPHS
int 0
If true, fetch quality graphs along with short reads. [csra_loader]
quality_graphs

CSRA_LOADER_QUALITY_GRAPHS
Boolean false

BAM

bamread library

Purpose [Registry section]
Registry name
Valid values Default
Specifies directory where BAM and BAM index files are looked for. [bam]
dir_path
Directory name  
Specifies BAM file name. If dir_path is also specified, then the file name is relative to the dir_path. [bam]
bam_name
File Name  
Specifies BAM index file name. If dir_path is also specified, then the file name is relative to the dir_path. If index_name is not set then index file name is derived form BAM file name by adding “.bai” extension. [bam]
index_name
File Name  
Enables CIGAR string in Seq-align Traceback ext object [bam]
cigar_in_align_ext
Boolean true
Enables skipping of CIGAR string with ambiguous match [bam]
omit_ambiguous_match_cigar
Boolean false
Enables 2nd generation of BAM parsing code [bam]
use_raw_index
Boolean false

ncbi_xloader_bam library

Purpose [Registry section]
Registry name
Valid values Default
Enables debugging log messages (if not zero), the higher the number, the more messages are logged. [bamloader]
debug
Number (0-3) 0
Specified file name for CIdMapperConfig used to map BAM sequence ids into CSeq_id. [bamloader]
mapper_file
File Name  
Generate pileup graphs for alignments [bamloader]
pileup_graphs
Boolean true
Do not create pileup graphs from the set (ACGT,match,insert) if the graph is completely zero. [bamloader]
skip_empty_pileup_graphs
Boolean true
Use fast estimation for coverage graph if possible. [bamloader]
estimated_coverage_graph
Boolean true
Do not open BAM files at time of loader registration, open them only when alignments or graphs are requested. [bamloader]
preopen
Boolean false

DBAPI

These parameters tune the behavior of the DBAPI library.

Table 14. DBAPI configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
If RESET_SYBASE is true, the Sybase client path will be set to the value in the SYBASE variable. [N/A]
N/A

RESET_SYBASE
Boolean  a (none)
If RESET_SYBASE is true, the Sybase client path will be set to the value in the SYBASE variable. [N/A]
N/A

SYBASE
a path containing a Sybase client (none)
The version of the TDS protocol to use with the CTLIB driver. [CTLIB]
TDS_VERSION

CTLIB_TDS_VERSION
an installed TDS version 125 (see API)
The version of the TDS protocol to use with the FTDS driver. [FTDS]
TDS_VERSION

FTDS_TDS_VERSION
0 (auto-detect),
50 (Sybase or Open Server),
70 (SQL Server)
0
Whether connecting with Kerberos authentication is supported. If true, and the username and password are empty strings, then DBAPI will attempt to use Kerberos to connect to the database. The user must ensure that the database will allow them to connect via Kerberos and that their Kerberos ticket is not expired. [dbapi]
can_use_kerberos

NCBI_CONFIG__DBAPI__CAN_USE_KERBEROS  c
Boolean  b false
Whether to encrypt login data. [dbapi]
conn_use_encrypt_data

NCBI_CONFIG__DBAPI__CONN_USE_ENCRYPT_DATA  c
Boolean  b false
The maximum number of simultaneously open connections to database servers. [dbapi]
max_connection

NCBI_CONFIG__DBAPI__MAX_CONNECTION  c
unsigned int 100
The maximum number of connection attempts that will be made for any server. [DB_CONNECTION_FACTORY]
MAX_CONN_ATTEMPTS

NCBI_CONFIG__DB_CONNECTION_FACTORY__MAX_CONN_ATTEMPTS  c
unsigned int 1
The maximum number of validation attempts that will be made for each connection. [DB_CONNECTION_FACTORY]
MAX_VALIDATION_ATTEMPTS

NCBI_CONFIG__DB_CONNECTION_FACTORY__MAX_VALIDATION_ATTEMPTS  c
unsigned int 1
The maximum number of servers to try to connect to for each service name (this is only meaningful if the number of servers running this service exceeds this value). [DB_CONNECTION_FACTORY]
MAX_SERVER_ALTERNATIVES

NCBI_CONFIG__DB_CONNECTION_FACTORY__MAX_SERVER_ALTERNATIVES  c
unsigned int 32
The maximum number of connections to be made to one particular server (when several connections to the same service name are requested) before an attempt to connect to another server will be made. A value of 0 means connect to the same server indefinitely. [DB_CONNECTION_FACTORY]
MAX_DISPATCHES

NCBI_CONFIG__DB_CONNECTION_FACTORY__MAX_DISPATCHES  c
unsigned int 0
The timeout, in seconds, to be used for all connection attempts (0 means to use either the default value or a value set specifically for the driver context). [DB_CONNECTION_FACTORY]
CONNECTION_TIMEOUT

NCBI_CONFIG__DB_CONNECTION_FACTORY__CONNECTION_TIMEOUT  c
unsigned int 30
The timeout, in seconds, to be used while logging into the server for all connection attempts (0 means to use either the default value or a value set specifically for the driver context). [DB_CONNECTION_FACTORY]
LOGIN_TIMEOUT

NCBI_CONFIG__DB_CONNECTION_FACTORY__LOGIN_TIMEOUT  c
unsigned int 30
If DBAPI resolved the passed name as a service name and then couldn’t connect to any server associated with that service name, then this parameter determines whether DBAPI should also try to resolve the passed name as a server name (a database alias from “interfaces” file or a DNS name). See also: database load balancing. [DB_CONNECTION_FACTORY]
TRY_SERVER_AFTER_SERVICE

NCBI_CONFIG__DB_CONNECTION_FACTORY__TRY_SERVER_AFTER_SERVICE  c
Boolean  a false
See ‘PRAGMA cache_size’ in the SQLite documentation. [LDS2]
SQLiteCacheSize

LDS2_SQLITE_CACHE_SIZE
any valid cache size for an SQLite database 2000
The parameter tells if the SET XACT_ABORT ON option should be sent to the server as the first thing when a new connection is created.
The parameter is applicable for the MS SQL servers only. The Sybase servers do not support this option and DBAPI will not try to send it regardless of the parameter value.
See more on MS SQL server documentation.
[dbapi]
set_xact_abort

NCBI_CONFIG__DBAPI__SET_XACT_ABORT c
Boolean b true

a case-insensitive: true, t, yes, y, false, f, no, n

b case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

c environment variable name formed from registry section and entry name

Eutils

These parameters tune the behavior of the Eutils library.

Table 15. eutils library configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Specify the base URL for Eutils requests. [Eutils]
Base_URL

EUTILS_BASE_URL
a valid URL https://www.ncbi.nlm.nih.gov/books/NBK25501/ (see API)

Distributed Computing (GRID) Specific Parameters

The following sections discuss configuration parameters that are specific to NCBI Distributed Computing (GRID).

Note: This section only applies within NCBI.

NetCache and NetSchedule

Table 16 describes configuration parameters that are common to both NetCache and NetSchedule client APIs. These parameters are found in the netservice_api registry section.

Table 16. Common NetCache and NetSchedule client API configuration parameters (netservice_api)

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Fail the request if the network I/O is inactive (blocked waiting for the communication channel to become readable or writable) for more than the specified timeout in seconds. Applies to all socket operations after the initial connection is established (see NCBI_CONFIG__NETSERVICE_API__CONNECTION_TIMEOUT). Can be overridden by NCBI_CONFIG__NETCACHE_API__COMMUNICATION_TIMEOUT or NCBI_CONFIG__NETSCHEDULE_API__COMMUNICATION_TIMEOUT. [netservice_api]
communication_timeout

NCBI_CONFIG__NETSERVICE_API__COMMUNICATION_TIMEOUT  a
floating point >= 0.0 (zero means default) 12.0 (see API for up-to-date default)
Turn on socket-specific logging, such as status and transferred data. [netservice_api]
connection_data_logging

NCBI_CONFIG__NETSERVICE_API__CONNECTION_DATA_LOGGING  a
Boolean  b false
The maximum number of times the API will retry a communication command on a socket. Setting connection_max_retries to zero will prevent NetCache API from retrying the connection and command execution. [netservice_api]
connection_max_retries

NCBI_CONFIG__NETSERVICE_API__CONNECTION_MAX_RETRIES  a
unsigned int 4
The timeout in seconds for establishing a new connection to a server. Can be overridden by NCBI_CONFIG__NETCACHE_API__CONNECTION_TIMEOUT or NCBI_CONFIG__NETSCHEDULE_API__CONNECTION_TIMEOUT. [netservice_api]
connection_timeout

N/A
floating point > 0.0, millisecond precision, minimum 0.001 (1 millisecond) 2.0 (see API for up-to-date default)
The number of connections to keep in the local connection pool. If zero, the server will grow the connection pool as necessary to accomodate new connections. Otherwise, when all connections in the pool are used, new connections will be created and destroyed. [netservice_api]
max_connection_pool_size

NCBI_CONFIG__NETSERVICE_API__MAX_CONNECTION_POOL_SIZE  a
non-negative int 0 (meaning unlimited)
The maximum number of attempts to resolve the LBSMD service name. If not resolved within this limit an exception is thrown. [netservice_api]
max_find_lbname_retries

NCBI_CONFIG__NETSERVICE_API__MAX_FIND_LBNAME_RETRIES  a
positive int 3
The delay in seconds between retrying a command; the total time should not exceed NCBI_CONFIG__NETCACHE_API__MAX_CONNECTION_TIME. [netservice_api]
retry_delay

NCBI_CONFIG__NETSERVICE_API__RETRY_DELAY  a
floating point >= 0.0 1.0 (see API for up-to-date default)
Close connections with zero timeout to prevent sockets in TIME_WAIT on the client side. By default, the Linux kernel delays releasing ports for a certain period after close() because there might be a delayed arrival of packets. Setting this parameter to true disables that behavior and therefore allows faster recycling of ports. This is important when the server is handling a large number of connections due to the limited number of ports available. [netservice_api]
use_linger2

NCBI_CONFIG__NETSERVICE_API__USE_LINGER2  a
Boolean  b false

a environment variable name formed from registry section and entry name

b case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

Table 17 describes configuration parameters for NetCache client applications. These parameters are found in the netcache_api registry section. Note: The netcache_api registry section was formerly called netcache_client.

Table 17. NetCache client API configuration parameters (netcache_api)

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Enable input caching (provides for slow blob retrieval). [netcache_api]
cache_input

N/A
Boolean  b false
Only applies when using CNetICacheClient. Provides a “namespace” for blobs. Thus, blobs are uniquely identified by the { key, version, subkey, cache_name } combination. [netcache_api]
cache_name

N/A
up to 36 characters (case-sensitive and no spaces) (none)
Enable output caching (provides for saving a blob with pauses more than “communication_timeout”). [netcache_api]
cache_output

N/A
Boolean  b false
The name of your application, as identified to NetCache. [netcache_api]
client

N/A
your application’s name (none)
Synonym for [netcache_api]/client, which is preferred. [netcache_api]
client_name

N/A
   
Can be used to override NCBI_CONFIG__NETSERVICE_API__COMMUNICATION_TIMEOUT. Please see that entry for details. [netcache_api]
communication_timeout

N/A
floating point >= 0.0 (zero means use the default from NCBI_CONFIG__NETSERVICE_API__COMMUNICATION_TIMEOUT) (none)
Can be used to override [netservice_api]/connection_timeout. Please see that entry for details. [netcache_api]
connection_timeout

N/A
floating point >= 0.0, minimum 0.001 (zero means use the default from [netservice_api]/connection_timeout) (none)
Depending on the value, enables mirroring: if true, mirroring is unconditionally enabled, if false, it is disabled completely. The special value “if_key_mirrored” is used to enable mirroring for the blobs that already have mirroring extensions in their keys. [netcache_api]
enable_mirroring

N/A
Boolean  c, or “if_key_mirrored” “if_key_mirrored”
The host:port address for the NetCache server that will be used for blob creation if none of the servers configured via LBSM were able to create the blob. This is only for new blob requests. [netcache_api]
fallback_server

NCBI_CONFIG__NETCACHE_API__FALLBACK_SERVER  a
a valid server ””
Sets a communication timeout (in seconds) for accessing the first server in a service while submitting a job. If the first server does not reply within the specified amount of time, the next server will be tried, but the second and all subsequent servers will be given the full communication_timeout to reply. If LBSM services are not used or there’s only one server in the service, this parameter does not apply. [netcache_api]
first_server_timeout

NCBI_CONFIG__NETCACHE_API__FIRST_SERVER_TIMEOUT  a
floating point >= 0.0 (zero means use default) [netschedule_api]/communication_timeout if defined, or 300ms
In conjunction with [netcache_api]/port, a synonym for [netcache_api]/service_name, which is preferred. [netcache_api]
host

N/A
   
Max total time for each NetCache transaction. [netcache_api]
max_connection_time

N/A
floating point >= 0.0 (zero means to ignore) 0.0
In conjunction with [netcache_api]/host, a synonym for [netcache_api]/service_name, which is preferred. [netcache_api]
port

N/A
   
A trigger for LBSM query (query LBSM once per the specified number of NetCache operations). [netcache_api]
rebalance_requests

N/A
integer >= 0 (zero means to not rebalance based on requests) 5000 requests
Another trigger for LBSM query (query LBSM at least once per the specified number of seconds) [netcache_api]
rebalance_time

N/A
floating point >= 0.0 (zero means to not rebalance based on time) 10.0 seconds
Synonym for [netcache_api]/host, which is preferred. [netcache_api]
server

N/A
   
Synonym for [netcache_api]/service_name. [netcache_api]
service

N/A
   
The LBSM name that specifies which servers to use. The service name is only used when creating blobs. [netcache_api]
service_name

N/A
any registered LBSM service (none)
This is one condition that will trigger server throttling and is defined as a string having the form “A / B” where A and B are integers. Throttling will be triggered if there are A failures in the last B operations.
[netcache_api]
throttle_by_connection_error_rate

N/A
a string having the form “A / B” where A and B are integers “0 / 0” (ignored)
This is another condition that will trigger server throttling and is defined as follows. Server throttling will be triggered if this number of consecutive connection failures happens.
[netcache_api]
throttle_by_consecutive_connection_failures

N/A
integer 0 (ignored)
Do not release server throttling until the server appears in LBSMD. [netcache_api]
throttle_hold_until_active_in_lb

N/A
Boolean  c false
Indicates when server throttling will be released. [netcache_api]
throttle_relaxation_period

N/A
integer time period in seconds 0 (throttling is disabled)
Where to save blob caches. [netcache_api]
tmp_dir

N/A
a valid directory (none)
Synonym for [netcache_api]/tmp_dir. [netcache_api]
tmp_path

N/A
   
A true value enables an alternative method for checking if a blob exists. Note: This option is available only for backward compatibility and should not be used. [netcache_api]
use_hasb_fallback

NCBI_CONFIG__NETCACHE_API__USE_HASB_FALLBACK  a
Boolean  b false
Defines LBSM affinity name to use for floor assignment, etc. [netcache_api]
use_lbsm_affinity

N/A
a valid affinity (none)
If this parameter is set to true, blob key contains service name and server (listed in the blob key) is not present in that service, then do not try to connect to that server. If set to ‘auto’ and key has a “Check-Server” hint set to NO, then assume ‘server_check = no’; otherwise, assume ‘server_check = yes’. Otherwise, unconditionally try to connect to the server. [netcache_api]
server_check
true/false/auto auto
This is a hint for the blob readers that use ‘server_check = auto’. If set to true, blob readers are advised to pre-check the server which is listed in the blob key. [netcache_api]
server_check_hint
true/false true

a environment variable name formed from registry section and entry name

b case-insensitive: true, t, yes, y, 1, false, f, no, n, 0

c case-insensitive: true, t, yes, y, false, f, no, n

Table 18 describes configuration parameters for NetSchedule client applications. These parameters are found in the netschedule_api registry section.

Table 18. NetSchedule client API configuration parameters (netschedule_api)

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Name of the queue (DO NOT use default queue for your application). [netschedule_api]
queue_name

N/A
your application’s queue name (none)
The name of your application, as identified to NetSchedule. [netschedule_api]
client_name

N/A
your application’s name (none)
Can be used to override NCBI_CONFIG__NETSERVICE_API__COMMUNICATION_TIMEOUT. Please see that entry for details. [netschedule_api]
communication_timeout

N/A
floating point >= 0.0 (zero means use the default from NCBI_CONFIG__NETSERVICE_API__COMMUNICATION_TIMEOUT) 12.0 seconds
Can be used to override [netservice_api]/connection_timeout. Please see that entry for details. [netschedule_api]
connection_timeout

N/A
floating point >= 0.0 (zero means use the default from [netservice_api]/connection_timeout) 2.0 seconds
Use affinity information when requesting jobs. [netschedule_api]
use_affinities
true/false false
Initial set of preferred affinities. Initial (comma/space separated) list of preferred affinities. Example: job_type_a, job_type_b [netschedule_api]
affinity_list
comma/space separated list ””
A prioritized lists of affinities, which overrides the default job processing order. Cannot be used with affinity_list. Example: high_priority_job, mid_priority_job, low_priority_job [netschedule_api]
affinity_ladder
comma/space separated list ””
Use affinity information and accept new affinities automatically. Cannot be used with affinity_ladder. [netschedule_api]
claim_new_affinities
true/false false
Allow the worker node to process jobs without affinities as well as jobs with “non-preferred” affinities. Cannot be used in combination with ‘claim_new_affinities’. [netschedule_api]
process_any_job
true/false false

Worker Node

Table 19 describes configuration parameters for Worker Nodes.

Table 19. Worker Node configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Deprecated. [server]
allow_implicit_job_return

NCBI_CONFIG__SERVER__ALLOW_IMPLICIT_JOB_RETURN  e
Boolean  b false
Maximum time worker nodes are allowed to live without a single NetSchedule server. [server]
max_wait_for_servers

NCBI_CONFIG__SERVER__MAX_WAIT_FOR_SERVERS  e
unsigned int 24 * 60 * 60 seconds
Causes the worker node to shut down if any jobs fail. [server]
stop_on_job_errors

NCBI_CONFIG__SERVER__STOP_ON_JOB_ERRORS  e
Boolean  b true
Maximum number of jobs(threads) can be served simultaneously. This parameter defines job parallelism. For computationally intensive algorithms this value should not be more than number of CPUs if set to ‘auto’, the node will determine the number of CPUs on the system and use this number. [server]
max_threads
  auto
Initial number of threads created for incoming jobs [server]
init_threads
  1
TCP/IP and UDP port number for control messages (like shutdown, version) and job notifications. It runs special control thread for incoming administrative requests (from netschedule_control and netschedule_admin) Can take a ports range (ex. 9300-9310). In this case the system will try to find an available port in the given range [server]
control_port
   
Server side logging. A worker node can ask its context if this flag is set to true [server]
log
   
Internal. Delay in seconds node task dispatcher waits for free space in the job queue. Lower value usually gives better response to shutdown command (CPU traded off) [server]
thread_pool_timeout
   
Time worker node spends waiting for new jobs without connecting to the netschedule server queue. Server sends UPD requests to wake the node up. Bigger values of this parameter reduces the netschedule server load in expense of job delivery latency (because of potential loss of UDP packages) [server]
job_wait_timeout
   
The max total number of jobs after which the node will shutdown itself. Restarting the node periodically is useful due to accumulating heap fragmentation possible leaks etc. [server]
max_total_jobs
  0 - means unlimited number of jobs.
The max number of failed jobs after which the node will shutdown itself. [server]
max_failed_jobs
  0 - means unlimited number of failed jobs.
When true, server transforms into a daemon, detached from the current program group (for UNIX only) [server]
daemon
   
The list of worker nodes which this node will check before attempting to retrieve a job from the NetSchedule queue. If at least one of these worker nodes has an ideal thread, this node will not connect to the queue for a job. This node and all nodes from the given list must be connected to the same NetSchedule service, the same queue and must run the same job. If the list is empty (defult) then this node is a master. [server]
master_nodes
  empty - this node is a master.
List of network hosts which are allowed admin access to the worker node if this worker node is controled by grid_node_watcher.sh don’t forget to to add “localhost” to this list. [server]
admin_hosts
   
Time delay (in seconds) between the node enters an idle mode (all jobs are done and there are no new jobs in the queue) and the idle task gets executed. Can not be less then 1 sec. [server]
idle_run_delay
  30
Specifies if an idle task works in an exclusive mode, which means that no real job will be processed until the idle task is running. [server]
idle_exclusive
  true
The node will automatically shut itself down if it is idle for a continuous period of time longer than this (in seconds): [server]
auto_shutdown_if_idle
  0 - means never auto shutdown
Specifies if the framework should reuse an instance of the job class. Setting this parameter to true means that only one instance of the job class will be create per each execution thread. False means that an instance of job class will be created per each incoming job. [server]
reuse_job_object
  false
Allows the node to detect infinite loops in job execution. If a job is being executed for more then the specified time, it is assumed to be stuck in an infinite loop. It this happens, the node enters shutdown mode, and when all other jobs, which may be running on this node, are done, the node terminates. [server]
infinite_loop_time
  0, which means that the node will not detect infinite loops.
Time in seconds. Specifies how often the node should check states of jobs it is processing. It is used as a feedback from the client to see if it wants to cancel the job execution [server]
check_status_period
   
Sets the maximum limit for total memory consumption by this worker node. When this limit is reached, the worker node shuts down. [server]
total_memory_limit
   
Sets the maximum limit for total runtime of this worker node (in seconds). When this limit is reached, the worker node shuts down. [server]
total_time_limit
  0, which means there is no limit.
Default timeout before the job is terminated in case of pullback. This value can be overridden by the ‘–timeout’ option specified with ‘grid_cli suspend –pullback’. [server]
default_pullback_timeout
   

See the Distributed Computing chapter for more information on NetCache and NetSchedule.

Configuration parameters for NetCache daemons are described in the file:

https://www.ncbi.nlm.nih.gov/viewvc/v1/trunk/c++/src/app/netcache/netcached.ini?view=log

Application-Specific Parameters

The following sections discuss configuration parameters that are specific to selected applications.

Seqfetch.cgi

Note: This applies only inside NCBI.

These parameters tune the behavior of the seqfetch.cgi application.

Table 19. seqfetch.cgi application configuration parameters

Purpose [Registry section]
Registry name

Environment variable
Valid values Default
Point to the current script. [SeqFetch]
Viewer_fcgi_path

SEQFETCH_VIEWER_FCGI_PATH
a valid path /sviewer/viewer.fcgi
Name the current load-balanced proxy. [SeqFetch]
Viewer_fcgi_proxy

SEQFETCH_VIEWER_FCGI_PROXY
a valid proxy name sviewer_lb