diff options
Diffstat (limited to 'p11p-daemon/README.md')
| -rw-r--r-- | p11p-daemon/README.md | 72 |
1 files changed, 45 insertions, 27 deletions
diff --git a/p11p-daemon/README.md b/p11p-daemon/README.md index c1910b8..e822935 100644 --- a/p11p-daemon/README.md +++ b/p11p-daemon/README.md @@ -52,56 +52,74 @@ Compile: ## Configuring p11p-daemon -Edit config/sys.config to define virtual tokens. +Edit config/sys.config to define virtual tokens and set other +configuration options. A PKCS #11 application ("client"), connecting to p11p-daemon performs PKCS #11 operations on a virtual token. Each virtual token represents one or more physical cryptographic devices with a PKCS #11 interface ("tokens"). -Each virtual token has a name, a mode and a list of PKCS #11 modules, -i.e. shared libraries. +Each virtual token has a name and a list of PKCS #11 modules, +i.e. shared libraries. Other configuration settings have resonable +defaults and are optional. ### vtoken name A string identifying a virtual token. This name is reflected in the name of the socket used by the client to connect to p11p-daemon. -### vtoken modules +#### failover -A list of PKCS #11 modules backing the virtual token. +If a token fails to respond within the number of milliseconds +specified in the 'timeout' configuration parameter, the next token in +the list becomes the active token. The list is circular, meaning that +the first token in the list is used after the last token in the list +has failed. This is true for a list with a single token as well. -Each entry in this list has a name, a path to the shared library to -load and, optionally, an environment to run it in. The environment can -be used to pass configuration to the module. +The 'failover' configuration parameter determines how many times this +switch will happen. The number of switches that will happen equals +'failover' minus one, so that a failover value of one will result in +zero retries, a value of two will result in one retry, and so forth. A +value of zero disables the failover functionality. -### vtoken mode +The default failover configuration value equals the number of tokens +listed in 'modules' minus one, resulting in one attempt being made per +token. -The mode of a virtual token determines some of its behaviour with -reagard to choosing which token to satisfy a client request. +TBD: Rename 'failover' to 'retries'? -#### failover +#### balance -In failover mode, the virtual token will use the first token in the -list of tokens until that token fails and then switch to the next in -the list. +A virtual token will balance client requests over all configured +tokens in accordance with the configuration parameter 'balance'. -Failover mode has one parameter specifying the number of seconds (?) -to wait for a token to respond before giving up and decide that the -token has failed. +The 'balance' configuration parameter is a list of invocation counts, +one per token. An invocation count is an integer specifying how many +times a token will be used before switching to the next token in the +list of tokens ('modules'). The first integer in the list corresponds +to the first token, the second integer to the second token, and so on. -#### balance +An invocation count of 0 disables load balancing for a given token, +meaning that once it has been chosen, it will stick. -In balance mode, the virtual token will balance client requests over -all configured tokens in accordance with its configuration parameter. +Note that there is no load balancing happening within one client +session with the p11p-daemon. The invocation count is affected only +when a client choses a token, which happens at client connect. + +The default invocation count is 0 for all tokens, effectively +disabling load balancing. + +### modules + +A list of PKCS #11 modules backing the virtual token. + +Each entry in this list has a name, a path to the shared library to +load and, optionally, an environment to run it in. The environment can +be used to pass configuration to the module. -Balance mode has one parameter, a list of invocation counts. An -invocation count is an integer specifying how many times a token -should be invoked before moving to the next in the list. The first -integer in the list corresponds to the first token, the second integer -to the second token, and so on. +TBD: rename to 'tokens'? -The default invocation count is one. ## Running p11p-daemon |