Domino AppDev Pack

1.0.5

Configuration

Proton is a Domino server add-in task that is part of the Domino AppDev Pack. The purpose of this task is to execute remote requests from applications written to use the domino-db API. Proton enables remote applications written in Node.js or Java that use the domino-db API to perform read/write operations on documents in a server database.

Configuration Settings

Each Domino server that runs Proton must have a Proton configuration document in the adpconfig.nsf database. See Domino Installation for information about creating the database on your Domino server.

There are two ways to create a configuration document in the Proton section of the database:

  • Select Add Server Configuration -> For new server... to create a configuration document for a server with the default settings.

  • Select Add Server Configuration -> Import server INIs.. to copy the notes.ini configuration settings from a server that was previously configured for the AppDev Pack before the 1.0.5 release.

The following sections describe the settings in the configuration document.

Server Settings

Domino Server Name

Identifies the name of the Domino server that uses the configuration document. Each Domino server that runs Proton must have its own configuration document.

If you try to start Proton on a Domino server that doesn't have a configuration document, Proton generates the following error and stops:

PROTON: Unable to find configuration document for '...' in database 'adpconfig.nsf': Entry not found in index

Enabled

Controls whether Proton is enabled on the given server. A change to this setting takes effect the next time Proton starts.

Listen Address

Controls the IP address Proton uses to listen for incoming network connections. Use "127.0.0.1" to bind to the local address. (Proton accepts connections only from the local machine.) Use "0.0.0.0" to bind to all IP addresses available on the machine. Otherwise, use another IP address that is available on the local machine.

Listen Port

Controls the port Proton uses to listen for incoming network connections. Specify a port that is available for use on the machine. For testing only, you can specify 0 to enable Proton to select a random, available port on the machine.

SSL Settings

Enable SSL/TLS connections

Enable this setting to allow Proton to accept TLS encrypted and authenticated connections. If enabled, you must provide a Domino Keyring File that contains the private key for the Proton server and one or more root certificates for establishing trust with clients.

Disable this setting to allow Proton to accept unencrypted and unauthenticated connections. This is a valid option if domino-db applications require only Anonymous access to Domino data.

Proton does not accept both encrypted and unencrypted requests at the same time.

Keyring File

Provide the name of the keyfile created with the Domino kyrtool. The keyfile must have the private key for the Proton add-in task. The file path is relative to the Domino server's data directory.

See this page for more information about creating the keyfile.

See this page for more information about using the Domino KYRTool.

Authentication

Client authentication

Controls how Proton authenticates clients. Valid options are:

  • Client Certificate - Authentication occurs through a client certificate is that mapped to a Person document in the server's directory. Access to data is calculated based on this identity. Proton must be enabled for TLS.

  • Anonymous - All requests are made as the Anonymous user identity. This name does not need to appear in the directory, but it does need to be given access in database ACLs. This option is available with and without TLS being enabled.

Enable Act-as-User Tokens

Indicates whether Act-as-User requests are available to domino-db applications. When disabled, Act-as-User requests will fail with the FEATURE_NOT_ENABLED error.

This setting is available only when TLS is enabled with client certificate authentication.

See this page for more information about the Act-as-User feature.

IAM Client Configuration Name

Identifies the name used with the oauthcfg tool to store the IAM introspection credentials that Proton uses to complete Act-as-User requests. The introspection credentials are created by IAM when you register the Proton Resource Provider. You then store these credentials in the Domino credential store using the oauthcfg tool under a name that you provide with the oauthcfg create command. Proton uses the value of this setting to find the credentials and URL to use to make introspection requests to the IAM service.

See the this page for more details about the oauthcfg tool.

This setting is available when TLS is enabled with Client Certificate Authentication.

Get ID file wait

Limits on the amount of time a request waits to retrieve an ID file from the ID vault. Proton applies this setting when domino-db requests require access to an application's ID file.

Session Limits

Session cache TTL

Controls the amount of time Proton caches the authentication entry for an application request or an Act-as-User request.

See the session cache section for more details.

Session cache max entries

Controls the number of authentication entries that Proton caches.

See the session cache section for more details.

Document Limits

Maximum note count

Controls the maximum number of documents Proton processes in a query found set. By default, Proton processes a maximum of 200 documents per request. A domino-db application may request more than the limit, but Proton caps the result size to this limit.

Warning: If Proton executes many simultaneous queries with large found sets, this setting can affect overall performance. You should find the right balance based on the applications running in your enterprise.

Attachments

Enable writing of attachments

Controls whether applications can write attachments to a Domino database. When this setting is disabled and an application attempts to write an attachment, Proton responds with the FEATURE_NOT_ENABLED error.

Maximum attachment size

Limits the attachments that can be written to Domino databases to the specified size, in megabytes (MB). A value of 0 (default) indicates no limit and that attachments of any size can be written.

Minimum attachment chunk size

Controls the minimum chunk size Proton uses when clients read an attachment. By default, the minumum chunk size is 4 KB. Specify a value between 1 KB to 8 KB.

This setting is the low value constraint in the chunkSizeKb of all the attachment related calls in the domino-db API.

Maximum attachment chunk size

Controls the maximum chunk size Proton uses when clients read an attachment. By default, the maximum chunk size is 32 KB. Specify a value from 8 KB to 64 KB.

This setting is the high value constraint in the chunkSizeKb of all the attachment related calls in the domino-db API.

Rich Text

Allow reading/writing of rich text

Controls whether applications can read and write rich text fields in a Domino database. When this setting is disabled and an application attempts to read or write a rich text field, Proton responds with the FEATURE_NOT_ENABLED error.

Maximum rich text size

Limits rich text fields that can written to databases. The default is 1024 MB.

Minimum rich text chunk size

Controls the minimum chunk size Proton uses when clients read rich text fields. By default, the minumum chunk size is 4 KB. Specify a value from 1 KB to 8KB.

This setting is the low value constraint in the chunkSizeKb of all the rich text related calls in the domino-db API.

Maximum rich text chunk size

Controls the maximum chunk size Proton uses when clients read rich text fields. By default, the maximum chunk size is 32 KB. Specify a value from 8KB to 64 KB.

This setting is the low value constraint in the chunkSizeKb of all the rich text related calls in the domino-db API.

Rate Limits

See the rate limit section for additional details.

Enable Act-as-User token rate limit

Controls whether rate limiting for the bad Act-as-User requests feature is enabled. Disabling is less secure. This setting is automatically disabled if Act-as-User is disabled.

Maximum number of applications in history

Controls the number of applications that Proton maintains for the purpose of identifying bad acting applications.

Number of bad requests allowed per application

This is a two value setting. The first value controls the number of bad requests allowed by an application. The second value controls the amount of time for bad requests from an application.

Jail time for abuse

Controls the amount of time applications are put in "jail" for sending abusive requests. Requests from a jailed application fail with the RATE_LIMIT_DENIED error.

Agents

Allow agents to execute

Controls whether domino-db agent.run() calls are allowed to execute. By default, an application using domino-db is allowed to run agents when database permissions allow it. A change to this setting requires a restart of Proton task.

JVM min heap

An optional parameter that Proton passes to the JVM at initialization to specify the initial size, in bytes, of the memory allocation pool. This setting is equivalent to the -Xms command line option used when running a Java application. Changes to this setting requires a restart of the Proton task.

If blank, JVM uses it's default value.

JVM max heap

An optional parameter Proton passes to the JVM at initialization to specify the maximum size, in bytes, of the memory allocation pool. This setting is equivalent to the -Xmx command line option used when running a Java application. Changes to this setting requires a restart of the Proton task.

If blank, JVM uses it's default value.

About the session cache

Requests from the domino-db module are authenticated. This operation includes the following steps which can be expensive to perform on every request:

  • Directory lookup to identify the functional id in the Domino directory
  • Client certificate validation against the Domino directory
  • Building of the nameslist and group expansion for the functional id
  • Retrieval of the id file for the functional id when needed

If it is an Act-as-User request, then the following steps are also performed:

  • Introspection call to the IAM service to verify the access token and retrieve the user information.
  • Directory lookup to identify the Act-as-User id in the Domino directory
  • Build the nameslist with group expansion for the Act-as-User id

To improve application peformance, the result of these operations are cached for the amount of time specified in the Session cache TTL setting. Proton will cache at most Session cache max entries. When the cache reaches this limit the least recently used entries are removed from the cache.

For better performance, minimize the number sessions removed from the cache due of the cache size limit. For better security keep the cache TTL low.

About bad request rate limits

When processing Act-as-User requests, Proton makes introspection calls to the IAM service to validate OAuth2 tokens. When unable to validate a token, Proton attempts again the next time the token is used. By default, if an application makes 50 failed validation requests within 1 minute, Proton refuses additional requests, sends the message "Service Refused," and "jails" the offending application for 2 minutes. This feature prevents rogue or malfunctioning applications from making excessive validation requests that can consume resources and degrade the server.

All requests from a jailed application are refused, including requests from the application and Act-as-User requests. Refused requests and other failed Act-as-User requests are logged as errors in the console with the prefix PROTON: NotAuthorized:.

See these settings to change related the default settings.

Working with the Proton add-in task

This section provides additional details related to using the Proton task as an administrator.

Starting and stopping the Proton add-in task

Use the load Domino server console command to load the Proton task:

> load proton
PROTON: Build 0.7.0-16
PROTON: Server initializing
JVM: Java Virtual Machine initialized.
PROTON: Listening on 0.0.0.0:3003, SSL-ENABLED
PROTON: Server initialized

Use the tell command to shutdown the Proton task:

> tell proton quit
PROTON: Server stopping
PROTON: Server exited

Automatically start Proton at Domino Server startup

The Domino notes.ini setting ServerTasks contains all the task names to automatically load at server startup. Add Proton to this notes.ini setting. You can edit the server's notes.ini directly with an editor if the server is not running. Or use Domino server console commands to add PROTON to the list. For example:

> show config servertasks
SERVERTASKS=Replica,Router,Update,AMgr,Adminp,Sched,CalConn,RnRMgr,LDAP
> set config SERVERTASKS=Replica,Router,Update,AMgr,Adminp,Sched,CalConn,RnRMgr,LDAP,PROTON

Show Configuration

To inspect the current Proton configuration settings, use the tell proton showconfig Domino server console command. Proton periodically checks for updates to its configuration document. The command also forces Proton to read the latest configuration settings.

> tell proton showconfig
Proton: Version                       : "..."
Proton: Configuration                 : "'...' loaded from note 2298"
Proton: Enabled                       : True
Proton: Valid                         : True
Proton: SSL                           : True
Proton: Keyfile                       : "protonserver.kyr"
Proton: Listen Address                : "0.0.0.0"
Proton: Listen Port                   : 3003
Proton: Allow Anonymous               : False
Proton: Allow Client Cert             : True
Proton: Allow Act-as-User             : True
Proton:  IAM Client Config            : "default"
Proton: Wait time for ID              : 18 seconds
Proton: Max Note Count                : 200 per request
Proton: Session Cache TTL             : 300 seconds
Proton: Session Cache Size            : 5000 entries
Proton: Allow Write Attachments       : True
Proton:  Min Attachment Chunk         : 4 KB
Proton:  Max Attachment Chunk         : 32 KB
Proton:  Max Write Attachment Size    : 0 MB
Proton: Allow Agent Run               : True
Proton:  JVM Min Heap                 : ""
Proton:  JVM Max Heap                 : ""
Proton: Enable Rate Limits            : True
Proton:  Max Applications             : 500
Proton:  Max Bad Requests             : 50
Proton:  Max Bad Requests Time        : 60 seconds
Proton:  Abuse jail time              : 120 seconds
Proton: Enable Rich Text Streaming    : False
Proton:  Min Rich Text Chunk          : 4 KB
Proton:  Max Rich Text Chunk          : 32 KB
Proton:  Max Rich Text Size           : 1024 MB

Statistics

The Proton addin task maintains a set of Domino statistics that provide a view into operational aspects of this service. Access the Proton statistics using the Domino server console command: show stat proton.

For example:

> show stat proton
   PROTON.Available = 1
   PROTON.Available.ElapsedSecs = 585
   PROTON.Build = ...
   PROTON.RateLimit.Jail.Count = 0
   PROTON.RateLimit.Jail.Total.Count = 0
   PROTON.RateLimit.Refused.Count = 0
   PROTON.RateLimit.RequestHistory.Count = 0
   PROTON.RateLimit.RequestHistory.Entries.Bytes = 0
   PROTON.RateLimit.RequestHistory.Entries.Count = 0
   PROTON.RateLimit.RequestHistory.LockTimeMS = 0
   PROTON.RateLimit.RequestHistory.LockWaitTimeMS = 0
   PROTON.Requests.Active.Current = 0
   PROTON.Requests.Active.Max = 0
   PROTON.Requests.Active.Total = 0
   PROTON.Request.Errors = 0
   PROTON.Request.Errors.OutOfMemory = 0
   PROTON.Request.QueryDB = 0
   PROTON.Request.QueryDB.Errors = 0
   PROTON.Request.QueryDB.Explain = 0
   PROTON.Session.Cache1.Count = 0
   PROTON.Session.Cache1.Entries.Bytes = 0
   PROTON.Session.Cache1.Entries.Count = 0
   PROTON.Session.Cache1.LockTimeMS = 0
   PROTON.Session.Cache1.LockWait0 = 0
   PROTON.Session.Cache1.LockWait1 = 0
   PROTON.Session.Cache1.LockWait2 = 0
   PROTON.Session.Cache1.LockWaitTimeMS = 0
   PROTON.Session.Cache1.Lookup.Expired = 0
   PROTON.Session.Cache1.Lookup.Hit = 0
   PROTON.Session.Cache1.Lookup.Miss = 0
   PROTON.Session.Cache1.Prune.Ejected = 0
   PROTON.Session.Cache1.Prune.Expired = 0
   PROTON.Session.Cache1.Save = 0
   PROTON.Session.Cache1.Save.Miss = 0
   PROTON.Session.IdCache.Errors = 0
   PROTON.Session.IdCache.GetIdFile.Total.Get.Err = 0
   PROTON.Session.IdCache.GetIdFile.Total.Get.Num = 0
   PROTON.Session.IdCache.GetIdFile.Total.Get.TimeMS = 0
   PROTON.Session.IdCache.GetIdFile.Total.ReGet.Num = 0
   PROTON.Session.IdCache.GetIdFile.Total.Wait.Err = 0
   PROTON.Session.IdCache.GetIdFile.Total.Wait.Num = 0
   PROTON.Session.IdCache.GetIdFile.Total.Wait.TimeMS = 0
   PROTON.Session.IdCache.Miss = 0
   PROTON.Session.Init.Errors = 0
   PROTON.Session.Lookup.Certificate = 0
   PROTON.Session.Lookup.Certificate.Errors = 0
   PROTON.Session.Lookup.IdVault = 0
   PROTON.Session.Lookup.IdVault.ConcurrentMax = 0
   PROTON.Session.Lookup.IdVault.Errors = 0
   PROTON.Session.Lookup.Token = 0
   PROTON.Session.Lookup.Token.Errors = 0
   PROTON.Threads.Active.Current = 1
   PROTON.Threads.Active.Max = 1
   PROTON.Threads.Active.Total = 1
   54 statistics found

Notes about the Proton statistics:

  • Session.Cache1.* statistics refer to the certificate based authentication cache operations.
  • Session.IdCache.* statistics refer to the use of the Id Vault cache when an application makes use of encryption operations.
  • Session.Lookup.* statistics refer to request authentication operations.
  • Request.* statistics refer to application request operations.
  • RateLimit.* statistics refer to rate limiting for bad Act-as-User requests data.
    • RateLimit.RequestHistory.Entries.Bytes - The size, in bytes, of all rate limit history entries.
    • RateLimit.Jail.Count - The number of applications currently in jail.
    • RateLimit.Jail.Total.Count - The total number of times any application has been placed in jail.
    • RateLimit.Refused.Count - The number of requests that have been refused due to the application being in jail.
← Domino InstallationAbout TLS support →