Replace Argon2 with Balloon hashing

[govpn.git] / doc / server.texi

diff --git a/doc/server.texi b/doc/server.texi
index 49a09fb990438998a7a939d354e650c800761120..325d317cb4b435f88398e56d51382166919c008f 100644 (file)
--- a/doc/server.texi
+++ b/doc/server.texi
@@ -1,75 +1,87 @@
 @node Server
 @section Server part
 
 @node Server
 @section Server part
 

-Except for common @code{-mtu}, @code{-stats}, @code{-egd} options server
-has the following ones:
+Except for common @ref{Stats, -stats}, @ref{EGD, -egd}, @ref{Syslog, -syslog}
+options server has the following ones:

 
 

-@table @code
+@table @option

 
 @item -proto
 
 @item -proto

-@ref{Network, network protocol} to use. Can be @emph{udp} (default),
+@ref{Network, Network protocol} to use. Can be @emph{udp} (default),

 @emph{tcp} or @emph{all}.
 
 @item -bind
 Address (@code{host:port} format) we must bind to.
 
 @item -conf
 @emph{tcp} or @emph{all}.
 
 @item -bind
 Address (@code{host:port} format) we must bind to.
 
 @item -conf

-Path to JSON file with the configuration.
+Path to YAML file with the configuration.

 
 @item -proxy
 Start trivial HTTP @ref{Proxy} server on specified @emph{host:port}.
 
 @end table
 
 
 @item -proxy
 Start trivial HTTP @ref{Proxy} server on specified @emph{host:port}.
 
 @end table
 

-Configuration file is JSON file with following example structure:
+Configuration file is YAML file with following example structure:

 
 @verbatim
 
 @verbatim

-{
-  "9b40701bdaf522f2b291cb039490312": {  <-- Peer identifier
-    "name": "stargrave",                <-- OPTIONAL human readable name
-    "up": "./stargrave-up.sh",          <-- up-script
-    "down": "./stargrave-down.sh",      <-- OPTIONAL down-script
-    "timeout": 60,                      <-- OPTIONAL overriden timeout
-    "noise": true,                      <-- OPTIONAL noise enabler
-                                            (default: false)
-    "cpr": 64,                          <-- OPTIONAL constant packet
-                                            rate in KiB/sec
-    "verifier": "2c15bbdffc73193bea56db412bce1143c68ccbdaa9e2eade53a684497646a685"
-  },
-  [...]
-}
+stargrave:                          <-- Peer human readable name
+    iface: tap10                    <-- OPTIONAL TAP interface name
+    mtu: 1515                       <-- OPTIONAL overriden MTU
+    up: ./stargrave-up.sh           <-- OPTIONAL up-script
+    down: ./stargrave-down.sh       <-- OPTIONAL down-script
+    timeout: 60                     <-- OPTIONAL overriden timeout
+    timesync: 0                     <-- OPTIONAL time synchronization requirement
+    noise: No                       <-- OPTIONAL noise enabler
+    cpr: 64                         <-- OPTIONAL constant packet rate, KiB/sec
+    encless: No                     <-- OPTIONAL Encryptionless mode
+    verifier: $baloon...            <-- verifier received from client
+[...]

 @end verbatim
 
 @end verbatim
 

-See @ref{Verifier} for its description.
+At least one of either @code{iface} or @code{up} must be specified. If
+you specify @code{iface}, then it will be forcefully used to determine
+what TAP interface will be used. If it is not specified, then
+up-@ref{Scripts, script} must output interface's name to stdout
+(first output line).
+
+For example up-script can be just @code{echo tap10}, or more advanced
+like the following one:

 
 

-up-script executes each time connection with the client is established.
-Its @emph{stdout} output must contain TAP interface name as the first
-line. This script can be simple @code{echo tap10}, or maybe more
-advanced like this:
-@example
+@verbatim

 #!/bin/sh
 $tap=$(ifconfig tap create)
 ifconfig $tap inet6 fc00::1/96 mtu 1412 up
 echo $tap
 #!/bin/sh
 $tap=$(ifconfig tap create)
 ifconfig $tap inet6 fc00::1/96 mtu 1412 up
 echo $tap

-@end example
+@end verbatim

 
 Each minute server rereads and refreshes peers configuration and adds
 newly appeared identities, deletes an obsolete ones.
 
 
 Each minute server rereads and refreshes peers configuration and adds
 newly appeared identities, deletes an obsolete ones.
 

-You can use convenient @code{utils/newclient.sh} script for new client
+You can use convenient @command{utils/newclient.sh} script for new client

 creation:
 
 @verbatim
 % ./utils/newclient.sh Alice
 [...]
 creation:
 
 @verbatim
 % ./utils/newclient.sh Alice
 [...]

-Your id is: 7012df29deee2170594119df5091d4a2
+Your client verifier is: $balloon$s=32768,t=16,p=2$bwR5VjeCYIQaa8SeaI3rqg

 
 

-Place the following JSON configuration entry on the server's side:
+Place the following YAML configuration entry on the server's side:

 
 

-    "906e34b98750c4f686d6c5489508763c": {
-        "name": "Alice",
-        "up": "/path/to/up.sh",
-        "verifier": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
-    }
-[...]
+    Alice:
+        up: /path/to/up.sh
+        iface: or TAP interface name
+        verifier: $balloon$s=32768,t=16,p=2$bwR5VjeCYIQaa8SeaI3rqg$KCNIqfS4DGsBTtVytamAzcISgrlEWvNxan1UfBrFu10
+@end verbatim
+
+Example configuration file:
+@verbatim
+stargrave:
+    iface: tap0
+    verifier: $balloon$s=32768,t=16,p=2$VMirzcshcHuG2V4jhUsEjw$X5fC07L8k61h3S1Oro/rC76+m0oGDTA9Bq+aWJ1uOgY
+slow:
+    iface: tap1
+    encless: Yes
+    mtu: 9000
+    cpr: 384
+    verifier: $balloon$s=32768,t=16,p=2$YbIA5garDqCOhtI/2EZVNg$gOo5vcEGynmpeepNscwclicfZsWxzgYFRLbgG21EZ1U

 @end verbatim
 @end verbatim