docs/afb-daemon-options.md

   1 # Launching options of afb-daemon
   2
   3 The launch options for binder **afb-daemon** are:
   4
   5 ```
   6  -v, --verbose           Verbose Mode, repeat to increase verbosity
   7  -q, --quiet             Quiet Mode, repeat to decrease verbosity
   8  -l, --log=xxxx          Tune log level
   9      --foreground        Get all in foreground mode
  10      --background        Get all in background mode
  11      --daemon            Get all in background mode
  12  -n, --name=xxxx         Set the visible name
  13  -p, --port=xxxx         HTTP listening TCP port  [default 1234]
  14      --roothttp=xxxx     HTTP Root Directory [default no root http (files not served but apis still available)]
  15      --rootbase=xxxx     Angular Base Root URL [default /opa]
  16      --rootapi=xxxx      HTML Root API URL [default /api]
  17      --alias=xxxx        Multiple url map outside of rootdir [eg: --alias=/icons:/usr/share/icons]
  18      --apitimeout=xxxx   Binding API timeout in seconds [default 20]
  19      --cntxtimeout=xxxx  Client Session Context Timeout [default 32000000]
  20      --cache-eol=xxxx    Client cache end of live [default 100000]
  21  -w, --workdir=xxxx      Set the working directory [default: $PWD or current working directory]
  22  -u, --uploaddir=xxxx    Directory for uploading files [default: workdir]
  23      --rootdir=xxxx      Root Directory of the application [default: workdir]
  24      --ldpaths=xxxx      Load bindings from dir1:dir2:... [default = /opt/jobol/lib64/afb]
  25  -b, --binding=xxxx      Load the binding of path
  26      --weak-ldpaths=xxxx Same as --ldpaths but ignore errors
  27      --no-ldpaths        Discard default ldpaths loading
  28  -t, --token=xxxx        Initial Secret [default=random, use --token= to allow any token]
  29  -r, --random-token      Enforce a random token
  30  -V, --version           Display version and copyright
  31  -h, --help              Display this help
  32      --ws-client=xxxx    Bind to an afb service through websocket
  33      --ws-server=xxxx    Provide an afb service through websockets
  34  -A, --auto-api=xxxx     Automatic load of api of the given directory
  35      --session-max=xxxx  Max count of session simultaneously [default 200]
  36      --tracereq=xxxx     Log the requests: no, common, extra, all
  37      --traceevt=xxxx     Log the events: no, common, extra, all
  38      --traceses=xxxx     Log the sessions: no, all
  39      --traceapi=xxxx     Log the apis: no, common, api, event, all
  40      --traceglob=xxxx    Log the globals: none, all
  41      --traceditf=xxxx    Log the daemons: no, common, all
  42      --tracesvc=xxxx     Log the services: no, all
  43  -c, --call=xxxx         call at start format of val: API/VERB:json-args
  44      --no-httpd          Forbid HTTP service
  45  -e, --exec              Execute the remaining arguments
  46  -M, --monitoring        Enable HTTP monitoring at <ROOT>/monitoring/
  47  -C, --config=xxxx       Load options from the given config file
  48  -Z, --dump-config       Dump the config to stdout and exit
  49  -s, --set=xxxx          Set parameters ([API]/[KEY]:JSON or {"API":{"KEY":JSON}}
  50  -o, --output=xxxx       Redirect stdout and stderr to output file
  51 ```
  52
  53 ## help
  54
  55 Prints help with available options
  56
  57 ## version
  58
  59 Display version and copyright
  60
  61 ## verbose
  62
  63 Increases the verbosity, can be repeated
  64
  65 ## quiet
  66
  67 Decreases the verbosity, can be repeated
  68
  69 ## log=xxxx
  70
  71 Tune the log level mask. The levels are:
  72
  73  - error
  74  - warning
  75  - notice
  76  - info
  77  - debug
  78
  79 The level can be set using + or -.
  80
  81 | Examples | descritpion
  82 |-----------------|-------------------
  83 | error,warning   | selects only the levels error and warning
  84 | +debug          | adds level debug to the current verbosity
  85 | -warning        | remove the level warning from the current verbosity
  86 | +warning-debug,info | Adds error and remove errors and warnings
  87
  88 ## port=xxxx
  89
  90 HTTP listening TCP port  [default 1234]
  91
  92 ## workdir=xxxx
  93
  94 Directory where the daemon must run [default: $PWD if defined
  95 or the current working directory]
  96
  97 ## uploaddir=xxxx
  98
  99 Directory where uploaded files are temporarily stored [default: workdir]
 100
 101 ## rootdir=xxxx
 102
 103 Root directory of the application to serve [default: workdir]
 104
 105 ## roothttp=xxxx
 106
 107 Directory of HTTP served files. If not set, files are not served
 108 but apis are still accessible.
 109
 110 ## rootbase=xxxx
 111
 112 Angular Base Root URL [default /opa]
 113
 114 This is used for any application of kind OPA (one page application).
 115 When set, any missing document whose url has the form /opa/zzz
 116 is translated to /opa/#!zzz
 117
 118 ## rootapi=xxxx
 119
 120 HTML Root API URL [default /api]
 121
 122 The bindings are available within that url.
 123
 124 ## alias=xxxx
 125
 126 Maps a path located anywhere in the file system to the
 127 a subdirectory. The syntax for mapping a PATH to the
 128 subdirectory NAME is: --alias=/NAME:PATH.
 129
 130 Example: --alias=/icons:/usr/share/icons maps the
 131 content of /usr/share/icons within the subpath /icons.
 132
 133 This option can be repeated.
 134
 135 ## apitimeout=xxxx
 136
 137 binding API timeout in seconds [default 20]
 138
 139 Defines how many seconds maximum a method is allowed to run.
 140 0 means no limit.
 141
 142 ## cntxtimeout=xxxx
 143
 144 Client Session Timeout in seconds [default 32000000 that is 1 year]
 145
 146 ## cache-eol=xxxx
 147
 148 Client cache end of live [default 100000 that is 27,7 hours]
 149
 150 ## session-max=xxxx
 151
 152 Maximum count of simultaneous sessions [default 200]
 153
 154 ## ldpaths=xxxx
 155
 156 Load bindings from given paths separated by colons
 157 as for dir1:dir2:binding1.so:... [default = $libdir/afb]
 158
 159 You can mix path to directories and to bindings.
 160 The sub-directories of the given directories are searched
 161 recursively.
 162
 163 The bindings are the files terminated by '.so' (the extension
 164 so denotes shared object) that contain the public entry symbol.
 165
 166 ## weak-ldpaths=xxxx
 167
 168 Same as --ldpaths but instead of stopping on error, ignore errors and continue.
 169
 170 ## binding=xxxx
 171
 172 Load the binding of given path.
 173
 174 ## token=xxxx
 175
 176 Initial Secret token to authenticate.
 177
 178 If not set, no client can authenticate.
 179
 180 If set to the empty string, then any initial token is accepted.
 181
 182 ## random-token
 183
 184 Generate a random starting token. See option --exec.
 185
 186 ## ws-client=xxxx
 187
 188 Transparent binding to a binder afb-daemon service through a WebSocket.
 189
 190 The value of xxxx is either a unix naming socket, of the form "unix:path/api",
 191 or an internet socket, of the form "host:port/api".
 192
 193 ## ws-server=xxxx
 194
 195 Provides a binder afb-daemon service through WebSocket.
 196
 197 The value of xxxx is either a unix naming socket, of the form "unix:path/api",
 198 or an internet socket, of the form "host:port/api".
 199
 200 ## foreground
 201
 202 Get all in foreground mode (default)
 203
 204 ## daemon
 205
 206 Get all in background mode
 207
 208 ## no-httpd
 209
 210 Forbids HTTP serve
 211
 212 ## exec
 213
 214 Must be the last option for afb-daemon. The remaining
 215 arguments define a command that afb-daemon will launch.
 216 The sequences @p, @t and @@ of the arguments are replaced
 217 with the port, the token and @.
 218
 219 ## tracereq=xxxx
 220
 221 Trace the processing of requests in the log file.
 222
 223 Valid values are 'no' (default), 'common', 'extra' or 'all'.
 224
 225 ## traceapi=xxxx
 226
 227 Trace the accesses to functions of class api.
 228
 229 Valid values are 'no' (default), 'common', 'api', 'event' or 'all'.
 230
 231 ## traceevt=xxxx
 232
 233 Trace the accesses to functions of class event.
 234
 235 Valid values are 'no' (default), 'common', 'extra' or 'all'.
 236
 237 ## call=xxx
 238
 239 Call a binding at start (can be be repeated).
 240 The values are given in the form API/VERB:json-args.
 241
 242 Example: --call 'monitor/set:{"verbosity":{"api":"debug"}}'
 243
 244 ## monitoring
 245
 246 Enable HTTP monitoring at <ROOT>/monitoring/
 247
 248 ## name=xxxx
 249
 250 Set the visible name
 251
 252 ## auto-api=xxxx
 253
 254 Automatic activation of api of the given directory when the api is missing.
 255
 256 ## config=xxxx
 257
 258 Load options from the given config file
 259
 260 This can be used instead of arguments on the command line.
 261
 262 Example:
 263
 264         afb-daemon \
 265                 --no-ldpaths \
 266                 --binding /home/15646/bindings/binding45.so \
 267                 --binding /home/15646/bindings/binding3.so \
 268                 --tracereq common \
 269                 --port 5555 \
 270                 --token SPYER \
 271                 --set api45/key:54027a5e3c6cb2ca5ddb97679ce32f185b067b0a557d16a8333758910bc25a72 \
 272                 --exec /home/15646/bin/test654 @p @t
 273
 274 is equivalent to:
 275
 276         afb-daemon --config /home/15646/config1
 277
 278 when the file **/home/15646/config1** is:
 279
 280         {
 281           "no-ldpaths": true,
 282           "binding": [
 283             "\/home\/15646\/bindings\/binding45.so",
 284             "\/home\/15646\/bindings\/binding3.so"
 285           ],
 286           "tracereq": "common",
 287           "port": 5555,
 288           "token": "SPYER",
 289           "set" : {
 290             "api45": {
 291               "key": "54027a5e3c6cb2ca5ddb97679ce32f185b067b0a557d16a8333758910bc25a72"
 292             }
 293           },
 294           "exec": [
 295             "\/home\/15646\/bin\/test654",
 296             "@p",
 297             "@t"
 298           ]
 299         }
 300
 301 The options are the keys of the config object.
 302
 303 See option --dump-config
 304
 305 ## dump-config
 306
 307 Output a JSON representation of the configuration resulting from
 308 environment and options.
 309
 310 ## output=xxxx
 311
 312 Redirect stdout and stderr to output file
 313
 314 ## set=xxxx
 315
 316 Set values that can be retrieved by bindings.
 317
 318 The set value can have different formats.
 319
 320 The most generic format is **{"API1":{"KEY1":VALUE,"KEY2":VALUE2,...},"API2":...}**
 321
 322 This example set 2 keys for the api *chook*:
 323
 324         afb-daemon -Z --set '{"chook":{"account":"urn:chook:b2ca5ddb97679","delay":500}}'
 325         {
 326            "set": {
 327              "chook": {
 328                "account": "urn:chook:b2ca5ddb97679",
 329                "delay": 500
 330              }
 331            }
 332          }
 333
 334 An other format is: **[API]/[KEY]:VALUE**.
 335 When API is omitted, it take the value "*".
 336 When KEY is ommitted, it take the value of "*".
 337
 338 The settings for the API \* are globals and apply to all bindings.
 339
 340 The settings for the KEY \* are mixing the value for the API.
 341
 342 The following examples are all setting the same values:
 343
 344         afb-daemon --set '{"chook":{"account":"urn:chook:b2ca5ddb97679","delay":500}}'
 345         afb-daemon --set 'chook/*:{"account":"urn:chook:b2ca5ddb97679","delay":500}'
 346         afb-daemon --set 'chook/:{"account":"urn:chook:b2ca5ddb97679","delay":500}'
 347         afb-daemon --set 'chook/account:"urn:chook:b2ca5ddb97679"' --set chook/delay:500
 348