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