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