DbDriverClassName

Java class name of the JDBC driver for your database engine that’s contained in the JAR file specified by DbDriverFile.  In a default installation (with MySQL as the database engine) this would be com.mysql.jdbc.Driver .

DbDriverFile

Complete file specification (path) to the JAR file that contains the code for the JDBC driver for the relational database engine that’s in use.  In a default installation (with MySQL as the backend database) this would be /usr/share/java/mysql-connector-java.jar .

DbUrl

The URI of the relational database engine, in a form that JDBC understands.  In a default installation (using MySQL as the database engine) the string should be

jdbc:mysql://localhost:3306/recipnet .

In order, the components of the string are a standard method tag, the name of the database engine in use, the host name of the database engine, the port the engine is listening on, and the database (or “catalog”) name to be used.  It is possible to cause recipnetd to connect to a database engine to a host other than the one on which recipnetd is running in this way.

DbUrlForBootstrap

Similar in form to DbUrl above, except this value is used only during so-called “bootstrap” operations like installing a new site or upgrading the site software from one version to another.  In a default installation this value is jdbc:mysql://localhost:3306/recipnet .

GenRecipnetdClassFile

Complete file specification (path) to the JAR file that contains the code for recipnetd.  In a default installation this would be /usr/share/java/recipnetd.jar.

GenRmiPort

The TCP port number on which recipnetd is to listen for incoming connections from the site software web application hosted by tomcat.  If both tomcat and recipnetd are present on a single server, it is recommended that this port be blocked in order to prevent other computers from interfering with this communication.  The default value is 1099 .

GenUtilityClassFile

Complete file specification (path) to the JAR file that contains the code for the various command-line utilities included in the recipnet package.  In a default installation this would be /usr/share/java/recipnet-utils.jar.

handlers

Java class name of the “handler” that recipnetd’s logging subsystem should use.  In a default installation this should be org.recipnet.site.core.SyslogHandler – this handler sends major events to GNU/Linux’s syslog mechanism.  It is possible to specify another class name here to cause log text to be written to stderr, for example.

IsmSuicideNote

Complete file specification (path) of a file that recipnetd will create to store debugging information in the event that a severe programming error is encountered.  The recipnet user must have write permission in the directory specified.  In a default installation this would be /tmp/recipnet-ismSuicideNote.txt .

LogCommand

Complete file specification (path) to the command-line utility that recipnetd invokes to send log messages to syslog (or a similar mechanism).  In a default installation this would be /usr/bin/logger.

LogFacilty

The name of the syslog ‘log facilty’ to which log events should be written.  The definitive reference for these is syslog’s man page, but possible values (at the time of this writing) are auth, authpriv, cron, daemon, ftp, kern, lpr, mail, news, syslog, user, uucp, and local0 to local7.  This should be user in a default installation.

This directive is ignored if handlers is not set to org.recipnet.site.core.SyslogHandler.

LogFilter

This can be set to the Java class name of a ‘log filter’ to be used by recipnetd’s logging subsystem.  The value of this directive should be blank in a default installation.

This directive is ignored if handlers is not set to org.recipnet.site.core.SyslogHandler.

LogForceSynchronous

Set to false in a default installation, but may also be true.  If false, log events are sent to GNU/Linux’s syslog facility asynchronously in order to improve performance.  However, in the event of a recipnetd crash, it is conceivable that log messages might be lost.  Set this to true to improve the chances that a log event would get written to syslog upon a crash of recipnetd.

This directive is ignored if handlers is not set to org.recipnet.site.core.SyslogHandler.

LogFormatter

This can be set to the Java class name of a ‘log formatter’ to be used by recipnetd’s logging subsystem.  Log formatters translate log events into plain text that is written to syslog.  The value of this directive should be blank in a default installation.

This directive is ignored if handlers is not set to org.recipnet.site.core.SyslogHandler.

LogLevel

The threshold that a log event (generated by recipnetd) must meet or exceed in order to be logged.  Possible values are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL, and OFF.  The recommended value is WARNING.  Note that it is possible to configure GNU/Linux’s syslog mechanism to enforce its own threshold, independent of the one specified here.

This directive is ignored if handlers is not set to org.recipnet.site.core.SyslogHandler.

LogTag

The textual ‘tag’ to use when sending log events to GNU/Linux’s syslog mechanism.  Tags can be useful when it comes time to analyze a combined log file generated by many different programs that all write to syslog.  This is set to recipnetd in a default installation, but may be changed to any other word.

This directive is ignored if handlers is not set to org.recipnet.site.core.SyslogHandler.

RepBaseDirectory

The base directory of the repository, the place where data files that have been attached to samples are stored.  In a default installation this would be /var/recipnet/data.

RepCvsCommand

The path on the local filesystem to GNU/Linux’s cvs program.  In a default installation this is /usr/bin/cvs .

RepCvsDirectory

The directory within the local site’s repository beneath which details about prior versions of sample data files should be archived.  In a default installation this value is /var/recipnet/data/cvs/ .

RepDbPassword

The password (in plaintext) associated with the database user account specified by RepDbUsername.

RepDbUsername

The name of the first of three database user accounts used by recipnetd to communicate with the backend database engine.  (The other two usernames are specified by SamDbUsername and SitDbUsername.)  The three user accounts specified should be distinct from one another in order to avoid concurrency conflicts, particularly with MySQL.

RepHoldingIdsCache

The first of several directives that control cache behavior inside recipnetd – tuning these values can have substantial performance implications both positive and negative.  Every cache directive takes seven parameters on a line that looks something like:

RepHoldingIdsCache=32,128,8,86400000,56000,0.1,false

This particular directive controls a cache in Repository Manager that matches sample id’s to the id’s of potentially many holding records in the database.

The seven cache parameters, in order, are:

Cache size: the maximum number of items the cache is able to store at once.  This must be larger than 0.

History log size: the maximum number of previous cache hits about which to keep statistics.  Accurate statistics assist the cache in optimizing itself.  Set this to 0 to disable hit logging (which can consume memory).

Cache chunk size hint: the approximate number of items that should be removed from the cache during each pruning operation.  Larger numbers here will reduce the needed frequency of pruning operations, which can be expensive.  This must be larger than 0.

Maximum age: the maximum number of milliseconds an item may live in the cache before it is considered to be expired and will be discarded.  Set this to 0 to disable item aging.

History log reduction interval: the number of milliseconds between cache log reduction operations, where the oldest record in the cache hit log is removed.  This feature can improve responsiveness of the cache’s self-optimizing mechanisms during periods of low activity.  The longest possible time an entry can live in the cache hit log is History log reduction interval * History log size.  Set this to 0 to disable history log reduction.

Random factor weight: a number between 0 and 1 that indicates the extent to which a randomly-generated factor is used to influence decisions about which cache items are more valuable to retain than others during pruning operations.  A random factor can be useful in improving performance when the working set is larger than the cache’s size.  If this value is 0.1, for example, then the relative scores of two cache items can be adjusted up to +/- 10%, according to the randomly-generated number.  Set this to 0 to negate the effect of the random number.  Exception: if history logging is disabled (by setting History log size to 0) then the Random factor weight has no upper bound.  In this case it represents the maximum number of milliseconds by which the ages of two cache items can be adjusted during scoring.

Secondary key support: set to either true or false.  In practice, secondary key support is necessary only for the SitUserCache and should be disabled everywhere else for performance reasons.   

RepHoldingsCache

Specifies parameters for a cache in Repository Manager that stores recently used “holding records” that have been read from the database.  The suggested parameters are 256,128,32,86400000,56000,0.1,false.  See RepHoldingIdsCache for a complete description of cache parameters.

RepPriorVersionFileSizeLimit

The maximum size, in bytes, of a sample data file for which unauthenticated users may request a prior version.  Making available prior versions of very large sample data files consumes a great deal of server resources; thus, allowing unauthenticated users to do so might pose a security risk.  The suggested value is 8388608 (8 megabytes).  The limit is not enforced for authenticated users affiliated with the sample in question.

RepPriorVersionTotalSizeLimit

The maximum size, in bytes, of the “available prior versions of sample data files area” on the local filesystem.  Sample data files are stored in this area temporarily to facilitate downloading, by user request, when they belong to a prior version of a sample.  If this limit is exceeded, files are rotated out of the area on a least-recently-used basis.  The suggested value is 4294867296 (4 gigabytes).

RepRandomizerTask

The first of several parameters that affect how periodic tasks are executed within recipnetd; these can affect both performance and usability.  Every task directive takes three parameters that looks something like:

RepRandomizerTask=300000,2000,0

The periodic task controlled by this particular directive helps to seed Repository Manager’s random number generator every now and then; it’s a very quick and low-cost operation.

The three task parameters, in order, are:

Approximate interval: the approximate number of milliseconds that should pass between successive executions of the periodic task.  It is not possible to schedule tasks for exactly periodic execution via this mechanism.

Maximum runtime: the maximum number of milliseconds this task might take to complete, under adverse circumstances.  This information is used to detect stalled tasks.

Characteristic: an integer composed of several flags that help the scheduling engine decide which task to run when.  Two tasks with the same characteristic bit set will not execute simultaneously.

RepRmiName

A string that specifies the name with which Repository Manager registers itself to RMI.  This value must match the corresponding entry in web.xml (used to configure the web application).  In a default installation, this value is RecipnetRepositoryManager.

RepScannerTask

Specifies parameters for a task in Repository Manager that scans the entire repository file system to look for newly-created sample data directories.  The suggested parameters are 3600000,600000,3.  See RepRandomizerTask for a complete description of periodic task parameters.

RepScriptCreateDir

Complete file specification (path) to the command-line utility that recipnetd invokes to create new data directories in the repository.  In a default installation this would be /usr/bin/recipnet-createreposdir.

RepScriptFixFile

Complete file specification (path) to the command-line utility that recipnetd invokes to fix permissions on newly-created data files in the repository.  In a default installation this would be /usr/bin/recipnet-fixreposfile.

RepScriptLabDirSize

Complete file specification (path) to the command-line utility that recipnetd invokes to discover the total size of a filesystem directory.  In a default installation this would be /usr/bin/recipnet-getrepositorysize.

RepUploadedFilePrefix

The prefix used to name temporary files created during uploads of sample data files.  Each temporary file created lies in its associated sample’s data directory.  The suggested value is .upload .  Because this value begins with a dot, on GNU/Linux this implies that all temporary upload files would be “hidden”.

RepWorkerThreadName

A string that specifies the name that Repository Manager gives to its worker thread.  In a default installation this value is RepositoryManager.

RepWorkerThreadShutdownTime

The maximum number of milliseconds Repository Manager’s worker thread may take to shut down before it’s considered to be stalled.  This is 5000 in a default installation.

RepWorkerThreadStartupTime

The maximum number of milliseconds Repository Manager’s worker thread may take to start up before it’s considered to be stalled.  This is 5000 in a default installation.

SamDbConnectionCount

The number of database connections that should be placed into the “sample- or repository-related” connection pool.  Database connections from this pool are used to fetch samples and execute sample searches.  This number governs the maximum number of “sample-related” operations your site will perform simultaneously and may have far-reaching performance implications.  This is 5 in a default installation.

SamDbPassword

The password (in plaintext) associated with the database user account specified by SamDbUsername.

SamDbUsername

See RepDbUsername.

SamIdBlockProposalPeriod

The maximum number of milliseconds that the distributed algorithm used by your site to generate new sample id blocks takes to finish.  The default value is 604800000 (7 days).

SamBulkFetchThreshold

A performance-tuning option that selects between two sample-fetching algorithms in various use cases.  The default value is 18.  Faster computers may benefit from higher numbers.

SamIdMaintenanceTask

Specifies parameters for a task in Sample Manager that checks to see if your site owns a sufficient number of sample id blocks and takes action to acquire more if necessary.   The suggested parameters are 21600000,60000,10.  See RepRandomizerTask for a complete description of periodic task parameters.

SamLocalLabIdAutoDigitsXXXXX

If present, enables sample number auto-generation for a particular lab.  Replace XXXXX with the numeric lab id.  Optional directive.  Use in conjunction with SamLocalLabIdPrefixXXXXX.  See page 46 for more information.

SamLocalLabIdPrefixXXXXX

If present, enables sample number auto-generation for a particular lab.  Replace XXXXX with the numeric lab id.  Optional directive.  Use in conjunction with SamLocalLabIdAutoDigitsXXXXX.  See page 46 for more information.

SamLockLogStackTraces

Either true or false.  Set this to true to enable detailed logging of recipnetd’s locking subsystem for debugging purposes.  Application performance is much better if this value is false, the suggested value.

SamLockTimeout

The maximum number of milliseconds that a user request should be delayed when the resources required to service the request are locked by another user.  Once this value is exceeded, the user receives a “deadlock” error.  The suggested value is 60000 (60 seconds).

SamPreexecuteSearches

Either true or false.  Set this to true to reduce the apparent latency when web users run sample searches.

SamRmiName

Similar to RepRmiName.  In a default installation this value is RecipnetSampleManager.

SamSampleCache

Specifies parameters for a cache in Sample Manager that stores sample records that have been read from the database.  The suggested parameters are 64,512,16,0,25000,0.1,false.  See RepHoldingIdsCache for a complete description of cache parameters.

SamSearchParamsCache

Specifies parameters for a place in Sample Manager that stores criteria for searches that users have run.  The maximum number of searches that can be active on a site at any one time is equal to the size of this cache.  When an item is dropped from this cache (whether due to age or space limitations) the search is no longer available and the user would need to respecify his search criteria.  The suggested parameters are 512,128,32,86400000,56000,0.1,false.  See RepHoldingIdsCache for a complete description of cache parameters.

SamSearchResultsCache

Specifies parameters for a cache in Sample Manager that stores search results for recently-run sample searches.  For efficiency’s sake, the size of this cache should be larger than the number of searches that are typically active on the local site at any time.  The suggested parameters are 32,128,4,3600000,56000,0.1,false.  See RepHoldingIdsCache for a complete description of cache parameters.

SamWorkerThreadName

Similar to RepWorkerThreadName.  In a default installation this value is SampleManager.

SamWorkerThreadShutdownTime

Similar to RepWorkerThreadShutdownTime.  This is 5000 in a default installation.

SamWorkerThreadStartupTime

Similar to RepWorkerThreadStartupTime.  This is 5000 in a default installation.

SamUnusedIdBlockLoanThreshold

A whole number that defines the minimum number of free sample id blocks your site will try to hold at any given time.  (Each sample id block contains 1024 globally unique sample id numbers that may be assigned to new sample records generated by your site.)  When the number of free sample id blocks owned by your site drops below this number, your site will refuse to “loan” sample id blocks to other sites when they run low.  The default value is 4, which is equal to the default value for SamUnusedIdBlockTarget.  This means that your site always will refuse to loan sample id blocks to other sites.

SamUnusedIdBlockMinimum

A whole number that defines the bare minimum number of free sample id blocks your site will hold at any given time.  When the number of free sample id blocks owned by your site drops below this number, your site will begin an urgent process to “borrow” additional sample id blocks from other sites.   The default value is 1.

SamUnusedIdBlockTarget

A whole number that defines the maximum number of free sample id blocks your site will try to hold at any given time  When the number of free sample id blocks owned by your site drops below this number, your site will attempt to acquire more blocks by coordinating with other sites in a distributed algorithm.  The default value is 4.

SitHttpConnectTimeout

The maximum number of milliseconds Site Manager will wait for an acknowledgement after attempting to transmit an inter-site message to a remote site before assuming that the remote site is down.  The default value is 10000.

SitHttpReadTimeout

The maximum number of milliseconds Site Manager will wait for a reply after requesting a “pull” of inter-site messages from the remote site.  The default value is 60000.

SitIsmProcessingTimeout

The maximum duration (in milliseconds) your site will spend attempting to process an inter-site message it received.  The default value is 300000 (5 minutes).  In practice, most inter-site messages are processed in less than 500 milliseconds.

SitLabCache

Specifies parameters for a cache in Site Manager that stores lab records that have been read from the database.  For efficiency’s sake, the size of this cache should be equal to or greater than the total number of labs in the Reciprocal Net Site Network.  The suggested parameters are 128,0,16,0,0,0,false.  See RepHoldingIdsCache for a complete description of cache parameters.

SitLocalFieldxxx

Replace xxx with any three-digit whole number from 000 to 999.  Creates a custom field (or “locally-defined field”) for samples created by the specified lab.  Lab users are able to attach extra textual metadata to samples in this way.  Optional directive.  See page 44 for more information.

SitMsgsAlwaysDump

Either true or false.  Set this to false for performance reasons unless you’re running additional software at your site that piggybacks on recipnetd’s mechanism for exchanging inter-site messages.

SitMsgsHeldDir

Complete directory specification (path) to the place where recipnetd should store message files for the inter-site messages that it has received but that cannot be processed yet.  The directory cannot be used for any other purpose and may not contain extraneous files.  In a default installation this would be /var/recipnet/msgs-held/.

SitMsgsHoldTime

The maximum number of milliseconds during which Site Manager will hold and attempt to redeliver a received inter-site message that encounters transient processing errors.  After this time has elapsed the message is dropped.  The default value is 604800000 (7 days).

SitMsgsPush

Either true (the default) or false.  When this value is true, any inter-site message that your site might generate will be transmitted to the destination site immediately (if possible).  When this value is false, the message will be held until the remote site next initiates a “pull” operation.

SitMsgsPushPredelay

The minimum number of milliseconds recipnetd should wait after generating an inter-site message before transmitting it across the Internet.  A nonzero value here increases the likelihood that a second message would be generated in the meantime, and thus that both messages could be sent in the same transmission for greater efficiency.  There’s a tradeoff here between latency and traffic volume in inter-site replication.  The recommended value is 2500 .

SitMsgsRecvDir

Complete directory specification (path) to the place where recipnetd should store message files for some of the inter-site messages it has received and processed.  The directory cannot be used for any other purpose and may not contain extraneous files.  In a default installation this would be /var/recipnet/msgs-recv/.

SitMsgsSentDir

Complete directory specification (path) to the place where recipnetd should store message files for all the inter-site messages it has transmitted.  The directory cannot be used for any other purpose and may not contain extraneous files.  In a default installation this would be /var/recipnet/msgs-sent/.

SitProviderCache

Specifies parameters for a cache in Site Manager that stores provider records that have been read from the database.  For efficiency’s sake, the size of this cache should be equal to or greater than the total number of providers in the Reciprocal Net Site Network.  The suggested parameters are 4096,0,32,0,0,0,false.  See RepHoldingIdsCache for a complete description of cache parameters.

SitRandomizerTask

Specifies parameters for a task in Site Manager that seeds the random number generator every now and then.   The suggested parameters are 300000,2000,0.  See RepRandomizerTask for a complete description of periodic task parameters.

SitRedeliverHeldMsgsTask

Specifies parameters for a task in Site Manager that automatically redelivers “held” inter-site messages from other sites that encountered processing errors previously.  The suggested parameters are 21600000,120000,8.  See RepRandomizerTask for a complete description of periodic task parameters.

SitReplayRequestTask

Specifies parameters for a task in Site Manager that “pulls” inter-site messages from other sites in the Site Network.  The suggested parameters are 3600000,120000,8.  See RepRandomizerTask for a complete description of periodic task parameters.

SitRmiName

Similar to RepRmiName.  In a default installation this value is RecipnetSiteManager.

SitReceivedIsmReplayLimit

A performance-tuning option that defines the size of message batches exchanged during inter-site synchronization in some cases.  The default value is 256.

SitSentIsmReplayLimit

A performance-tuning option that defines the size of message batches exchanged during inter-site synchronization in some cases.  The default value is 256.

SitShunnedDuration

The duration (in milliseconds) that your site will avoid synchronizing with another site in the Site Network that is offline.  After this timeout expires, synchronization may be attempted again.  The default value is 14400000 (4 hours).

SitSiteCache

Specifies parameters for a cache in Site Manager that stores site records that have been read from the database.  For efficiency’s sake, the size of this cache should be equal to or greater than the total number of sites in the Reciprocal Net Site Network.  The suggested parameters are 128,0,16,0,0,0,false.  See RepHoldingIdsCache for a complete description.

SitStatsCommitTask

Specifies parameters for a task in Site Manager that “writes behind” in-memory statistics counters to ensure that usage statistics would not be lost if recipnetd were to crash suddenly.  The suggested parameters are 3600000,120000,11.  See RepRandomizerTask for a complete description of periodic task parameters.

SitTidyUpTask

Specifies parameters for a task in Site Manager that releases memory resources and old pointers every now and then.   The suggested parameters are 7200000,30000,1.  See RepRandomizerTask for a complete description of periodic task parameters.

SitUserCache

Specifies parameters for a cache in Site Manager that stores user records that have been read from the database.  For efficiency’s sake, the size of this cache should be equal to or greater than the number of user accounts on the local site.  The suggested parameters are 256,0,16,0,0,0,true.  See RepHoldingIdsCache for a complete description of cache parameters.

SitWorkerThreadShutdownTime

Similar to RepWorkerThreadShutdownTime.  This is 5000 in a default installation.

SitWorkerThreadStartupTime

Similar to RepWorkerThreadStartupTime.  This is 5000 in a default installation.

SitWorkerThreadName

Similar to RepWorkerThreadName.  In a default installation this value is SiteManager.