inifile.rst
1 ================= 2 INI file sections 3 ================= 4 5 This document describes knxd's configuration file format. 6 7 General considerations 8 ====================== 9 10 INI-style files generally look like this:: 11 12 [section-name] 13 option=value 14 another-option=42 15 bool-option=true 16 17 Recognized boolean values are "1", "y" or "true" vs. "0", "n" or "false". 18 19 An option ``use=foo`` may be used to pull in options from another section. 20 21 knxd must be called with one or two arguments: 22 23 * config file 24 25 The name of the config file to read. '-' is used for standard input. 26 27 There is no default. 28 29 * main section 30 31 The section to use for the KNX router itself. 32 33 The default is "main". 34 35 Unrecognized options are fatal. Unused sections are not. 36 37 Command-line options 38 -------------------- 39 40 Previous versions of knxd used position-dependent options instead of a 41 configuration file. These are now deprecated. A translation program, 42 typically installed as ``/usr/lib/knxd_args``, will emit a correct 43 configuration file when called with the old knxd's arguments. ``knxd`` 44 automatically calls ``knxd_args`` when it is started with "old" arguments 45 and interprets the resulting file. This may cause error messages to refer 46 to strange options instead of command-line arguments. 47 48 The following documentation mentions the old arguments. Note that 49 argument order is significant. All filters in front of -e|--eibaddr apply 50 globally; filters after that apply to the driver or server following them. 51 Filters after the last driver or server, apply to the systemd-socket-passed 52 server(s). Modifiers like ``--arg=name=value`` apply to the filter, driver or 53 server they're directly in front of. 54 55 As an example, these arguments:: 56 57 knxd_args -e 1.2.3 -E 1.2.4:5 -D --arg=delay=50 -B pace -R --layer2=log -T -S -b tpuarts:/dev/ttyACM0 -f 9 -t 252 -B log 58 59 generate this configuration file (re-ordered for clarity):: 60 61 [main] 62 addr = 1.2.3 63 client-addrs = 1.2.4:5 64 connections = server,B.tpuarts 65 systemd = systemd 66 67 [B.tpuarts] 68 device = /dev/ttyACM0 69 driver = tpuart 70 71 [server] 72 server = ets_router 73 discover = true 74 debug = debug-server 75 router = router 76 tunnel = tunnel 77 78 [debug-server] 79 name = mcast:knxd 80 81 [router] 82 filters = A.pace 83 84 [A.pace] 85 delay = 50 86 filter = pace 87 88 [tunnel] 89 filters = log 90 91 [systemd] 92 debug = debug-systemd 93 filters = log 94 95 [debug-systemd] 96 error-level = 0x9 97 trace-mask = 0xfc 98 99 The config file generation code tries to keep the generated file reasonably 100 simple. Thus the "log" filters (unlike the "pace" filter) don't have a 101 section of their own, because they don't have arguments. 102 103 At startup, knxd will set up all configured drivers (unless they're 104 marked with ``ignore``). 105 If a driver fails, knxd will terminate with an error. 106 Use the ``retry`` filter to modify this. 107 108 109 main 110 ==== 111 112 The main section controls configuration of the whole of knxd. Its name 113 defaults to "main". An alternate main section may be named on the command 114 line. 115 116 * name (string; ``-n|--Name``) 117 118 The name of this server. This name will be used in logging/trace output. 119 It's also the default name used to announce knxd on multicast. 120 121 Optional; defaults to "knxd". 122 123 * addr (string: KNX device address; ``-e|--eibaddr``) 124 125 The KNX address of knxd itself. Used e.g. for requests originating at the 126 group cache. 127 128 Example: 1.2.3 129 130 Mandatory. 131 132 * client-addrs (string: KNX device address plus length; ``-E|--client-addrs``) 133 134 Address range to be distributed to client connections. Note that the 135 length parameter indicates the number of addresses to be allocated. 136 137 Example: 1.2.3:5 138 139 (This assigns addresses 1.2.3 through 1.2.7 to knxd's clients.) 140 141 Mandatory if you use knxd's server code (if in doubt: yes, you do). 142 143 * connections (string: list of section names; ``-b|--layer2 …``) 144 145 Comma-separated list of section names. Each named section describes 146 either a device to exchange KNX packets with, or a server which a 147 remote device or program may connect to. 148 149 Mandatory, as knxd is useless without any connections. 150 151 On the command line, a --layer2= option compiles all preceding filter 152 and debug parameters into a config file section. This also applies to 153 the options --eibaddr (global data), --listen-tcp, --listen-local, 154 --Routing, --Tunnelling, --Server, and --Groupcache. 155 156 * systemd (string: section name; implied at the end of the argument list) 157 158 Section name for describing connections managed by ``systemd.socket``. 159 160 The named section may be missing or empty:: 161 162 [main] 163 systemd=systemd 164 165 [systemd] 166 error-level=fatal 167 168 * cache (string: section name; ``-c|--GroupCache``) 169 170 Section name for the group cache. See the `group cache` section at the 171 end of this document for details. 172 173 Optional; mostly-required if you have a GUI that accesses KNX. 174 175 * force-broadcast (bool; ``--allow-forced-broadcast``) 176 177 Packets have a "hop count", which determines how many routers they may 178 traverse until they're discarded. This mitigates the problems caused by 179 bus loops (routers reachable by more than one path). 180 181 A maximum hop count is specified to (a) never be decremented, (b) such 182 packets are broadcast to every interface instead of just those their 183 destination address says they should go to. 184 185 knxd ignores this requirement unless you set this option, because it's 186 almost never useful and escalates configuration errors from "minor 187 annoyance" to "absolute disaster if such a packet ever gets tramsmitted". 188 189 Optional; default false. 190 191 * unknown-ok (bool; ``-A|--arg=unknown-ok=true``) 192 193 Mark that arguments ``knxd`` doesn't know would emit a warning instead 194 of being fatal. This is useful if you want a config file that allows 195 for backwards compatibility. 196 197 Optional; default false, to catch typos and thinkos. 198 199 * stop-after-setup (bool; ``-A|--arg=stop-after-setup=true``) 200 201 Usually, knxd exits if there are any fatal configuration errors. 202 This option will instruct it to terminate even if there are no errors. 203 You can thus use this option to verify that a configuration parses 204 correctly. 205 206 Optional; default false, also available as a command-line option. 207 208 Non-systemd options 209 ------------------- 210 211 These options will be ignored when you start knxd with systemd. 212 213 * pidfile (string: file name; ``-p|--pid-file=FILENAME``) 214 215 File to write knxd's process ID to. 216 217 Optional, default: false. 218 219 * background (bool; ``-d|--daemon``) 220 221 Instructs knxd to fork itself to the background. 222 223 Optional, default: false. 224 225 * logfile (string: file name; ``-d|--daemon=FILENAME``) 226 227 Tells knxd to write its output to this file instead of stderr. 228 229 Optional, default: /dev/stderr. 230 231 The file is closed and re-opened when you send a SIGHUP signal to knxd. 232 233 On the command line, this option implied forking to the background. 234 235 Debugging and logging 236 ===================== 237 238 You can selectively enable logging or tracing. 239 240 * debug (string: section name; implicit when using ``--error=`` or ``--trace=``) 241 242 This option, available in all sections, names the config file section 243 where specific debugging options for this section can be configured. 244 245 Optional; if missing, read debug options from the current section, or 246 from the main section. 247 248 A "debug" section may contain these options: 249 250 * error-level (string or int; ``-f|--error=LEVEL``) 251 252 The minimum severity level of error messages to be printed. 253 254 Possible values are 0…6, corresponding to none fatal error warning note info debug. 255 256 Optional; default: warning. 257 258 * trace-mask (int; ``-t|--trace=MASK``) 259 260 A bitmask corresponding to various types of loggable messages to help 261 tracking down problems in knxd or one of its devices. 262 263 For the meaning of possible values, read the source code. Notable bit 264 positions: 265 266 * 0 267 268 byte-level tracing. 269 270 * 1 271 272 Packet-level tracing. 273 274 * 2 275 276 Driver state transitions. 277 278 This level used to also be used for logging KNX packets in a 279 human-readable way; this has been subsumed by the "log" filter. 280 281 * 3 282 283 Dispatcher state transitions. 284 285 The dispatcher (src/libserver/router.cpp) is the heart of knxd. it 286 controls all drivers and decides to which drivers to re-distribute 287 incoming packets. 288 289 * 4 290 291 Anything that's not a driver and talks directly to the dispatcher 292 (group cache, high-level functions exposed by knxd's internal 293 protocol). Also some more dispatcher states. 294 295 * 6 296 297 Debugging of flow control issues. 298 299 Optional; default: no tracing. 300 301 Thus, if you want to debug packet-level tracing and flow control, you'd 302 use ``trace-mask=0x42``. If you don't know what is happening and want a 303 full debug log, ``0xffe`` is often useful. 304 305 .. Note:: 306 307 "packet-level tracing" does *not* include the data / control messages 308 that are exchanged between the KNXD core and one of its drivers. You 309 need to also add ``-B log`` if you want to see what's going on. 310 311 This is not the default because you often need different subsets for 312 verbosity and messaging. 313 314 .. Note:: 315 316 TODO: decide on a reasonable set of message types and allow selecting them 317 by name. 318 319 * timestamps (bool; ``--no-timestamp``) 320 321 Flag whether messages should include timestamps (since the start of knxd). 322 323 You may turn these off when your logging system already reports with 324 sufficient granularity or when you require reproducible logging output 325 for tests. 326 327 Optional; default: true. 328 329 The defaults are also used when no debug section exists. 330 331 Drivers 332 ======= 333 334 A driver is a link to a KNX interface or router which knxd establishes when 335 it starts up. (In contrast, a server (below) is a point of connection which 336 knxd establishes so that other interfaces, routers or clients may connect 337 to it.) 338 339 Each interface in your "main" section names a section where that 340 interface's driver is configured. If a driver doesn't need any 341 configuration you may just use the name of the driver. Thus:: 342 343 [main] 344 connections=foo,… 345 346 and:: 347 348 [main] 349 connections=my-driver,… 350 351 [my-driver] 352 driver=foo 353 354 are equivalent, as are:: 355 356 [main] 357 connections=my-driver,… 358 359 [my-driver] 360 driver=foo 361 some-options=true 362 363 and:: 364 365 [main] 366 connections=foo,… 367 368 [foo] 369 some-options=true 370 371 On the command line, driver options used to be added after the driver name, 372 separated by colons. The order of options reflects this. For example, the 373 driver "tpuart" accepted "device" and "baudrate" options; this command line:: 374 375 -b tpuarts:/dev/ttyACM0:19200 376 377 would be translated to a section:: 378 379 [X.tpuarts] 380 driver=tpuart 381 device=/dev/ttyACM0 382 baudrate=19200 383 384 Common options 385 -------------- 386 387 These options apply to all drivers and servers. 388 389 * ignore (bool; ``--arg=ignore=true``) 390 391 The driver is configured, but not started up automatically. 392 393 *Note*: Starting up knxd still fails if there is a configuration error. 394 395 dummy 396 ----- 397 398 This driver discards all packets. 399 400 It does not have any options. 401 402 ip 403 -- 404 405 This driver attaches to the IP multicast system. It is a minimal version of 406 the ``ets_router`` server's routing code (no tunnel server, no autodiscovery). 407 408 .. Warning:: 409 410 **Never** use this driver and the ``ets_router`` server at the same time (unless you 411 specify different multicast addresses). 412 413 * multicast-address (string: IP address) 414 415 The multicast IP address to use. 416 417 Optional; the default is 224.0.23.12. 418 419 * port (int) 420 421 The UDP port to listen on / transmit to. 422 423 Optional; the default is ``3671``. 424 425 * interface (string: interface name) 426 427 The IP interface to use. 428 429 Optional; the default is the first broadcast-capable interface on your 430 system, or the interface which your default route uses. 431 432 .. Note:: 433 434 You **must** use a multicast address here. Direct links to Ip 435 interfaces are called "tunnels" and accessed with the ``ipt`` driver, 436 below. 437 438 ipt 439 --- 440 441 This driver is a tunnel client, i.e. it attaches to a remote tunnel server. 442 Hardware IP interfaces frequently use this feature. 443 444 You may need the "single" filter in front of this driver. 445 446 Note that some of these devices exhibit an implementation bug: after 3.5 447 weeks an internal timer overruns (the number of milliseconds exceeds 2³¹). 448 If this happens, add a "retry-delay" option to cause knxd to reconnect 449 instead of terminating. 450 451 * ip-address (string: IP address) 452 453 The address (or host name) of the tunnel server to connect to. 454 455 Mandatory. 456 457 * dest-port (int) 458 459 The port to send to. 460 461 Optional; the default is 3671. 462 463 * src-port (int) 464 465 The port to send from. 466 467 Optional; by default, the OS will assign a free port. 468 469 * nat (bool; implied by using ``iptn`` instead of ``ipt``) 470 471 Require network address translation. 472 473 TODO: when would you need that? 474 475 * heartbeat-timer (int; seconds) 476 477 Timer for periodically checking whether the server is still connected 478 to us. 479 480 The default is 30. 481 482 * heartbeat-retries 483 484 Retry timer for coping with lost heartbeat packets. 485 486 The default is 3. If more consecutive heartbeat packets are unanswered, 487 the interface will be considered failed. 488 489 The following options are not recognized unless "nat" is set. 490 491 * nat-ip (string: IP address) 492 493 Target IP address for the tunnelling servers responses and requests. 494 When set to zero the server shall use the IP address in the IP packet received. 495 496 Defaults to "0.0.0.0" if "nat" is set, otherwise ignored. 497 498 * data-port (int) 499 500 Target port number for the tunnelling servers responses and requests. 501 502 Defaults to 0 if "nat" is set, otherwise ignored. 503 504 .. Note:: 505 506 You **must not** use a multicast address here. Using multicast links 507 is called "routing"; multicast is accessed either with the ``ip`` 508 driver, above, or the ``ets_router`` server, below. 509 510 iptn 511 ---- 512 513 See ``ipt``. 514 515 usb 516 --- 517 518 This driver talks to "standard" KNX interfaces with USB. These interfaces 519 use the HID protocol, which is almost but not quite entirely unsuitable for 520 KNX but has the advantage that you can plug such an adapter into any 521 Windows computer and start ETS, without installing a special driver. 522 523 Usually, you do not need any options unless you have more than one of these 524 interfaces or it has non-standard configuration, as knxd will find it by itself. 525 526 You may need the "single" filter in front of this driver. 527 528 You may need a UDEV rule that changes the USB device's ownership to knxd. 529 530 These devices use one of three related protocols: EMI1, EMI2, or CEMI. The 531 driver auto-detects wvich version to use. 532 533 Warning: bus+device numbers may change after rebooting. 534 535 * bus (int) 536 537 The USB bus the interface is plugged into. 538 539 * device (int) 540 541 The interface's device number on the bus. 542 543 It's an error to specify this option without also using "bus". 544 545 * config (int) 546 547 The USB configuration to use on this device. Most interfaces only have 548 one, so this option is not needed. 549 550 It's an error to specify this option without also using "device". 551 552 * setting (int) 553 554 The setting to use on this device configuration. Most interfaces only 555 have one, so this option is not needed. 556 557 It's an error to specify this option without also using "config". 558 559 * interface (int) 560 561 The interface to use on this setting. Most interfaces only 562 have one, so this option is not needed. 563 564 It's an error to specify this option without also using "setting". 565 566 * version 567 568 The EMI protocol version to use (1, 2, or 3). 569 570 Default: None, the protocol to be used is auto-detected. 571 572 The following options control repetition of unacknowledged packets. They 573 also apply to the "ft12" and "ft12cemi" drivers which wrap EMI1 / CEMI data 574 in a serial protocol. 575 576 * send-timeout (int; ``--send-timeout=MSEC``) 577 578 USB devices confirm packet transmission. This option controls how long 579 to wait until proceeding. A warning is printed when that happens. 580 581 The default is 300 milliseconds. 582 583 Note that this driver's old "send-delay" option is misnamed, as the 584 timeout is pre-emted when the remote side signals that is has accepted 585 the packet. 586 587 * send-retries (int) 588 589 The number of times to repeat the transmission of a packet. If 590 (ultimately) unsuccessful, the packet will be discarded. 591 592 The default is 3. 593 594 tpuart 595 ------- 596 597 A TPUART or TPUART-2 interface IC. These are typically connected using either 598 USB or (on Raspberry Pi-style computers) a built-in 3.3V serial port. 599 600 * device (string: device file name) 601 602 The device to connect to. 603 604 Optional; the default is /dev/ttyKNX1 which is a symlink created by a 605 udev rule, which you need anyway in order to change the device's owner. 606 607 * baudrate (int) 608 609 Interface speed. This is interface specific, and configured in hardware. 610 611 Optional; the default is 19200. 612 613 * low-latency (bool) 614 615 Try to set serial latency even lower. 616 617 This defaults to off because it doesn't work on every serial interface. 618 619 Alternately you can use:: 620 621 socat TCP-LISTEN:55332,reuseaddr /dev/ttyACM0,b19200,parenb,raw 622 623 on a remote computer, and connect to it via TCP. The options to use are 624 625 * ip-address=REMOTE 626 627 The IP address (or host name) of the system ``socat`` runs on. 628 629 Mandatory. 630 631 * dest-port=PORTNR 632 633 The TCP port to connect to. 634 635 Mandatory; use whatever free port you used on ``socat``'s command line. 636 637 On the command line, these drivers are called "tpuarts" and "tpuarttcp", for 638 compatibility with earlier versions. 639 640 ft12 641 ---- 642 643 An older serial interface to KNX which wraps the EMI1 protocol in serial framing. 644 645 TODO: which devices use this? 646 647 * baudrate (int) 648 649 Interface speed. This is interface specific, and configured in hardware. 650 651 Optional; the default is 19200. 652 653 * low-latency (bool) 654 655 Try to set serial latency even lower. 656 657 This defaults to off because it doesn't work on every serial interface. 658 659 * send-timeout (``--arg=send-timeout=MSEC``) 660 661 EMI1 devices confirm packet transmission. This option controls how long 662 to wait until proceeding. A warning is printed when that happens. 663 664 The default is 0.3 seconds. 665 666 As with "tpuart", this device can be used remotely. On the command line, 667 the driver's name is "ft12tcp". Use this command on the remote side:: 668 669 socat TCP-LISTEN:55332,reuseaddr /dev/ttyACM0,b19200,parenb,raw 670 671 The "send-timeout" and "send-retries" options, described above on the "usb" 672 driver, can also be applied to this driver. 673 674 ft12cemi 675 -------- 676 677 A newer serial interface to KNX. 678 679 TODO: which devices use this? 680 681 * baudrate (int) 682 683 Interface speed. This is interface specific, and configured in hardware. 684 685 Optional; the default is 19200. 686 687 * low-latency (bool) 688 689 Try to set serial latency even lower. 690 691 This defaults to off because it doesn't work on every serial interface. 692 693 * send-timeout (int; ``--arg=send-timeout=MSEC``) 694 695 CEMI devices confirm packet transmission. This option controls how long 696 to wait until proceeding. A warning is printed when that happens. 697 698 The default is 0.3 seconds. 699 700 As with "tpuart", this device can be used remotely. On the command line, 701 the driver's name is "ft12cemitcp". Use this command on the remote side:: 702 703 socat TCP-LISTEN:55332,reuseaddr /dev/ttyACM0,b19200,parenb,raw 704 705 The ``send-timeout`` and ``send-retries`` options, described above on the "usb" 706 driver, can also be applied to this driver. 707 708 ncn5120 709 ------- 710 711 A mostly-TPUART2-compatible KNX interface IC. 712 713 This driver uses the same options as "tpuarts". Its default baudrate is 714 38400. 715 716 As with "tpuart", this device can be used remotely. On the command line, 717 the driver's name is "ncn5120tcp". Use this command on the remote side:: 718 719 socat TCP-LISTEN:55332,reuseaddr /dev/ttyACM0,b38400,raw 720 721 More common options 722 ------------------- 723 724 Some drivers accept these options. 725 726 * ack-group (bool; ``--tpuarts-ack-all-group``) 727 728 Accept all group-addressed packets, instead of checking which knxd can 729 forward. This option is usually a no-op because knxd forwards all 730 packets anyway. 731 732 This option only applies to drivers which directly connect to a 733 twisted-pair KNX wire. 734 735 Optional; default false. 736 737 * ack-individual (bool; ``--tpuarts-ack-all-individual``) 738 739 Accept all device-addressed packets, instead of checking which knxd can 740 forward. This option is not a no-op because, while knxd defaults to 741 forwarding all packets, it won't accept messages to devices that it 742 knows to be on the bus on which the message in question arrived. 743 744 This option only applies to drivers which directly connect to a 745 twisted-pair KNX wire. 746 747 Optional; default false. 748 749 * reset (bool; ``--tpuarts-disch-reset``) 750 751 Reset the device while connecting to it. This also affects 752 reconnections due to timeout. 753 754 Optional; default false. 755 756 * monitor (bool; ``--no-monitor``) 757 758 Use this device as a bus monitor. 759 760 When this option is set, no data will be sent to or accepted from this device. 761 It will be set to bus-monitor mode and all incoming messages will only 762 be forwarded to bus-monitoring clients. 763 764 Optional; default false. 765 766 If you want to monitor a specific device while using it normally, use 767 the "monitor" filter instead. 768 769 If you want to log all packets passing through knxd, use the 770 "vbusmonitor" commands instead. 771 772 There is no way to switch between bus monitoring and normal mode. 773 This is intentional. 774 775 Before v0.12, knxd did not adequately distinguish between monitoring 776 and normal operation; instead, it switched the first interface without a 777 --no-monitor option to monitoring whenever a client wanted a bus 778 monitor. This no longer happens. 779 780 Servers 781 ======= 782 783 A server is a point of connection which knxd establishes so that other 784 interfaces, routers or clients may connect to it. (In contrast, a driver is 785 a link to a KNX interface or router which knxd establishes when it starts up.) 786 787 Common options 788 -------------- 789 790 See the "Common options" section under "Drivers", above. 791 792 ets_router 793 ---------- 794 795 The "ets_router" server allows clients to discover knxd and to connect to it 796 with the standardized KNX tunneling or routing protocols. 797 798 .. Warning:: 799 800 **Never** use this server and the ``ip`` driver at the same time (unless you 801 specify different multicast addresses). 802 803 * tunnel (str; ``-T|--Tunnelling``) 804 805 Allow client connections via tunneling. This is typically used by 806 single devices or programs. 807 808 This option names a section with configuration for tunnelled 809 connections. It's OK if that section doesn't exist or is empty. 810 811 Optional; tunneling is disabled if not set. 812 813 * router (str; ``-R|--Routing``) 814 815 Exchange packets via multicast. This is typically used by other KNX 816 routers. 817 818 This option names a section with configuration for the multicast 819 connection. It's OK if that section doesn't exist or is empty. 820 821 Optional; multicast is disabled if not set. 822 823 * discover (bool; ``-D|--Discovery``) 824 825 Reply to KNX discovery packets. Programs like ETS send these packets to 826 discover routers and tunnels. 827 828 Optional; default false. 829 830 * multi-port (bool; ``--multi-port`` / ``--single-port``) 831 832 If set, instructs knxd to use a separate port for exchanging KNX data 833 instead of using the default port. This allows two KNX routers (knxd or 834 otherwise) to co-exist on the same computer. 835 836 Unfortunately, using a single port is so common that some programs, 837 like ETS, ignore packets from a different port, even if that port is 838 announced in the discovery phase. 839 840 Optional; default false (for now). 841 842 * interface (string; 3rd option of ``-S``/``--Server``) 843 844 The IP interfce to use. Useful if your KNX router has more than one IP 845 interface. 846 847 Optional; defaults to the interface with the default route. 848 849 * multicast-address (string: IP address; 1st option of -S/--Server) 850 851 The multicast IP address to use. 852 853 Optional; the default is 224.0.23.12. 854 855 * port (int; 2nd option of ``-S``/``--Server``) 856 857 The UDP port to listen on / transmit to. 858 859 Optional; the default is 3671. 860 861 * name (string; not available) 862 863 The server name announced in Discovery packets. 864 865 Optional: default: the name configured in the "main" section, or "knxd". 866 867 * heartbeat-timeout (integer: keep-alive timeout) 868 869 The maximum time between status messages from tunnel clients. A client 870 that doesn't send any packets for this long is disconnected. 871 872 On the command line, this server is typically used as "-DTRS". The 873 -S|--Server argument has to be used last and accepted the options mentioned 874 above. 875 876 tcptunsrv 877 ---------- 878 879 The "tcptunsrv" server allows clients to connect knxd using the KNXnet/ip 880 TCP tunneling protocol. 881 882 * tunnel (str) 883 884 This option names a section with configuration for tunnelled 885 connections. It's OK if that section doesn't exist or is empty. 886 887 * port (int) 888 889 The TCP port to listen on / transmit to. 890 891 Optional; the default is 3671. 892 893 * systemd-ignore (bool) 894 895 Ignore this server when knxd is started via systemd. 896 897 Optional; default "true" if listening on TCP port 3671. 898 899 * heartbeat-timeout (integer: keep-alive timeout) 900 901 The maximum time between status messages from tunnel clients. A client 902 that doesn't send any packets for this long is disconnected. 903 904 unixtunsrv 905 ---------- 906 907 The "unixtunsrv" server allows clients to connect knxd using the KNXnet/ip 908 TCP tunneling protocol over Unix domain sockets. 909 910 * tunnel (str) 911 912 This option names a section with configuration for tunnelled 913 connections. It's OK if that section doesn't exist or is empty. 914 915 * path (string: file name) 916 917 Path to the socket file to use. 918 919 * systemd-ignore (bool) 920 921 Ignore this server when knxd is started via systemd. 922 923 Optional; default is "false" 924 925 * heartbeat-timeout (integer: keep-alive timeout) 926 927 The maximum time between status messages from tunnel clients. A client 928 that doesn't send any packets for this long is disconnected. 929 930 knxd_unix 931 --------- 932 933 Allow local knxd-specific clients to connect using a Unix-domain socket. 934 935 * path (string: file name; 1st option to ``-u|--listen-local``) 936 937 Path to the socket file to use. 938 939 Optional; default /run/knx. 940 941 * systemd-ignore (bool; ``--arg=systemd-ignore=BOOL``) 942 943 Ignore this option when knxd is started via systemd. 944 945 Optional; default "true" if no path option is used. 946 947 knxd_tcp 948 -------- 949 950 Allow remote knxd-specific clients to connect using a TCP socket. 951 952 * ip-address (string: IP address; 1st option to ``-i|--listen-tcp``) 953 954 Bind to this address. 955 956 Default: none, i.e. listen on all addresses the system is using. 957 958 * port (int; 2nd option to ``-i|--listen-tcp``) 959 960 TCP port to bind to. 961 962 Optional; default 6720. 963 964 * systemd-ignore (bool; ``--arg=systemd-ignore=BOOL``) 965 966 Ignore this option when knxd is started via systemd. 967 968 Optional; default "true" if no port option is used. 969 970 Filters 971 ======= 972 973 A filter is a module which is inserted between the knx router itself and a 974 specific driver. You specify filters with a ``filters=`` option in the 975 driver's or server's section. 976 977 On the command line, ``-B|--filter=NAME`` told knxd to apply this filter to the 978 next-specified driver. 979 980 Each filter names a section where that filter is configured. If a filter 981 doesn't need any configuration you may just use the name of the filter. 982 Thus:: 983 984 -B foo -B bar -b some-driver 985 986 translates to:: 987 988 [some-driver] 989 filters=foo,bar 990 991 which is equivalent to:: 992 993 [my-driver] 994 driver=some-driver 995 filters=my-foo,my-bar 996 997 [my-foo] 998 filter=foo 999 1000 [my-bar] 1001 filter=bar 1002 1003 For a more elaborate example:: 1004 1005 --arg=some-option --filter=foo --arg=an-option_a-value --layer2=some-driver 1006 1007 translates to:: 1008 1009 [my-driver] 1010 driver=some-driver 1011 filters=my-filter,… 1012 an-option=a-value 1013 1014 [my-filter] 1015 filter=foo 1016 some-option=true 1017 1018 If you just use:: 1019 1020 -B foo -b some-driver 1021 1022 this can be simplified to:: 1023 1024 [some-driver] 1025 filters=foo 1026 1027 Of course, all of these examples also add the driver's section name 1028 ("my-driver" or "some-driver") to the ``connections=`` parameter in the main 1029 section. 1030 1031 Filters are applied in order; conceptually, the knx router is added at the 1032 beginning of the filter list, while the driver itself is at the end. 1033 Transmitted packets pass that chain from beginning to end, while received 1034 packets move the other way. 1035 1036 If you specify filters on a server, each driver that's started by the 1037 server gets this set of filters. 1038 1039 single 1040 ------ 1041 1042 This filter allows knxd to connect to devices which only expect (or accept) 1043 a single device. Thus, on outgoing packets knxd will remember the sender's 1044 address in order to re-address any replies (if they're addressed 1045 individually). 1046 1047 * address (``--arg=address=N.N.N``) 1048 1049 The "single" filter typically uses knxd's address. However, that 1050 address is also used for multicast and thus is on the wrong line. 1051 1052 Thus, you can use this option to assign a different address. 1053 1054 If you use this filter behind an ``ipt:`` driver, the address it uses will be 1055 replaced with the one assigned by the remote server. 1056 1057 remap 1058 ----- 1059 1060 This filter allows knxd to connect to devices which internally use 1061 somewhat-random addresses. This may happen when a remote system reconnects 1062 and re-uses its old address instead of the new one. 1063 Thus, on incoming packets knxd will remember the sender's 1064 address in order to re-address any replies (if they're addressed 1065 individually). 1066 1067 This filter can also be used to connect remote networks with 1068 physical addresses that collide with whatever is connected to the rest of 1069 knxd. 1070 1071 Unlike the "single" filter, "remap" does not take an address parameter 1072 because its whole point is to use the address assigned to the link by knxd. 1073 1074 retry 1075 ----- 1076 1077 If a driver fails, the default behavior is to terminate knxd. 1078 You can use this module to restart the driver instead. 1079 1080 Also, this module can be used to restart a driver if transmission 1081 of a message takes longer than some predefined time. 1082 1083 This module is transparently inserted in front of line drivers. 1084 1085 * max-retries (int, counter) 1086 1087 The maximum number of retries when opening a driver or sending a packet. 1088 1089 The default is one: if the first attempt fails, the error is propagated 1090 to the router. Set to zero if the number of retries should not be limited. 1091 1092 For compatibility with older configuration, this option may be used 1093 on the driver. 1094 1095 * retry-delay (float, seconds) 1096 1097 The time before (re-)opening the driver when a failure occurred. 1098 1099 The default is zero: no timeout. 1100 1101 For compatibility with older configuration, this option may be used 1102 on the driver. 1103 1104 * send-timeout (float, seconds) 1105 1106 The time after which a message must have been transmitted. 1107 Otherwise the driver is closed and re-opened. 1108 1109 The default is zero: no timeout. 1110 1111 This option is also accepted on some drivers, but the semantics is 1112 different: the ``retry`` filter always restarts the driver before 1113 retrying, whereas the driver should assume a soft transmission error. 1114 1115 * start-timeout (float, seconds) 1116 1117 The maximum time (re-)opening the driver may take. 1118 1119 The default is zero: no timeout. 1120 1121 * flush (bool) 1122 1123 Flag whether to-be-transmitted packets are discarded while the driver is down. 1124 1125 The default is False: packet transmission will halt. You might want to use a ``queue`` 1126 filter in front of ``retry``. 1127 1128 * may-fail (bool) 1129 1130 Flag whether the initial start of this driver may fail, i.e. if set, this module 1131 affects the driver's initial start-up. 1132 1133 The default is False, i.e. retrying only kicks in after the driver is operational. 1134 1135 For compatibility with older configuration, this option may be used 1136 on the driver. 1137 1138 queue 1139 ----- 1140 1141 The normal behavior of knxd is to couple the transmission speed of all its 1142 interfaces, so that packets are transmitted on all of them (if they request 1143 them) at roughly the same speed, i.e. that of the slowest interface. 1144 1145 This filter implements a queue which decouples an interface, so that its 1146 speed does not affect the rest of the system. 1147 1148 The "queue" filter does not yet have any parameters. 1149 1150 Currently, a queue can grow without bounds; it also does **not** filter 1151 multiple packets to the same group address. 1152 1153 pace 1154 ---- 1155 1156 Limit the rate at which packets are transmitted to an interface. 1157 1158 * delay (float, msec) 1159 1160 The delay between transmissions. 1161 1162 Optional. The default is 15 msec. 1163 1164 * delay-per-byte (float, msec) 1165 1166 Additional delay per byte of longer messages, in milliseconds. 1167 1168 Note that protocol headers and other overhead is ignored here. 1169 The fixed-overhead part of the KNX protocol must be factored into the 1170 ``delay`` parameter. 1171 1172 Optional; the default is 1 msec, which roughly corresponds to one byte 1173 at 9600 baud (speed of the KNX bus). 1174 1175 * incoming (float, proportion) 1176 1177 The "pace" filter only considers outgoing packets. However, 1178 since KNX is a bus, incoming data also need to be considered. 1179 1180 This parameter controls whether incoming data should contribute to the 1181 filter's delay. 1182 1183 Optional. The default is 0.75. 1184 1185 The pace filter's timer starts when a packet has successfully been 1186 transmitted. Thus it should only be necessary in front of the multicast 1187 driver (which does not have transmission confirmation). However, there are 1188 buggy KNX interfaces out there which acknowledge reception of packets 1189 *before* checking whether they have free buffer space for more data … 1190 1191 Note that knxd schedules packet transmission synchronously. Thus, this 1192 filter acts globally (it delays sending to *all* interfaces) unless 1193 there is a ``queue`` filter in front of it. 1194 1195 If you use this filter to rate-limit a sender by more than the recipient's 1196 data rate, you should set the ``incoming`` parameter to zero. Otherwise a 1197 high rate of incoming messages will block the sender entirely. 1198 1199 .. Note:: 1200 1201 If you need this filter for reliable operation on an "ipt" tunnel 1202 interface, this is an indication of sloppy programming on the other 1203 end. A gateway *must not* acknowledge a message which it then 1204 throws away, presumably because its send buffer is full. 1205 1206 Please file a complaint with the gateway's manufacturer. 1207 1208 monitor 1209 ------- 1210 1211 This filter forwards all packets passing through it to knxd's bus monitoring 1212 system. 1213 1214 * recv (bool; ``--arg=recv=BOOL``) 1215 1216 Monitor incoming packets. Defaults to true. 1217 1218 * send (bool; ``--arg=send=BOOL``) 1219 1220 Monitor outgoing packets. Defaults to true. 1221 1222 1223 log 1224 --- 1225 1226 This filter logs all packets passing through it to knxd's logging system. 1227 1228 * name (string; ``--arg=name=NAME``) 1229 1230 Set the output's name. The default is "logsection/driversection". 1231 1232 * recv (bool; ``--arg=recv=BOOL``) 1233 1234 Log incoming packets. Defaults to true. 1235 1236 * send (bool; ``--arg=send=BOOL``) 1237 1238 Log outgoing packets. Defaults to true. 1239 1240 * state (bool; ``--arg=state=BOOL``) 1241 1242 Log state transitions (link up/down). Defaults to true. 1243 1244 * addr (bool; ``--arg=addr=BOOL``) 1245 1246 Log address checks, i.e. whether the driver knows and/or accepts 1247 a particular device or group address. Defaults to false. 1248 1249 * monitor (bool; ``--arg=monitor=BOOL``) 1250 1251 Log bus monitor packets. Defaults to false. 1252 1253 dummy 1254 ----- 1255 1256 This filter does nothing. 1257 1258 Special settings 1259 ================ 1260 1261 These are enabled by naming them in designated wntries of your main section. 1262 1263 Thus, you enable the group cache with:: 1264 1265 [main] 1266 cache=gc 1267 [gc] 1268 max-size=200 1269 1270 If you don't want to use any parameters, you don't need to add the section:: 1271 1272 [main] 1273 cache=gc 1274 1275 group cache 1276 ----------- 1277 1278 * max-size (int; option of ``-c|--GroupCache``) 1279 1280 The maximum number of messages that the group cache will store. 1281 1282 Optional; no default = no limit. There are 65535 possible group address 1283 entries which only occupy a few bytes each, so the recommended usage is 1284 to not specify a maximum. 1285 1286 This is the optional parameter of the ``--GroupCache`` argument. 1287