README.rst

   1 ***************************************
   2 Auerswald Callnotifier for COMpact 3000
   3 ***************************************
   4
   5 Connects to the debug port of your Auerswald Compact 3000 telephony switchboard
   6 and listens for incoming calls.
   7 It will notify you whenever a call comes in.
   8
   9 It also listens for outgoing calls if you want that, and you can log
  10 incoming and/or outgoing calls into a file or a database.
  11
  12 Callnotifier is able to resolve the names of calls via LDAP and the
  13 caller location city names via OpenGeoDb.
  14
  15 Blog post: https://cweiske.de/tagebuch/auerswald-callnotifier.htm
  16
  17 .. contents::
  18
  19
  20 ============
  21 Installation
  22 ============
  23
  24 1. Clone the git repository
  25 2. Install dependencies
  26 3. Configure the tool
  27 4. Run ``./callnotifier.php``
  28
  29
  30 Dependencies
  31 ============
  32 - PEAR's Console_CommandLine package
  33 - PEAR's Net_LDAP2 package for LDAP name resolution
  34 - curl for the dreambox notifier
  35
  36
  37 Systemd service
  38 ===============
  39
  40 1. Copy ``scripts/systemd/auerswald-callnotifier.service`` to ``/etc/systemd/system/``
  41 2. Adjust user and group name and callnotifier path
  42 3. Enable the service::
  43
  44     $ systemctl daemon-reload
  45     $ systemctl enable auerswald-callnotifier
  46     $ systemctl start auerswald-callnotifier
  47     $ systemctl status auerswald-callnotifier
  48
  49
  50 =============
  51 Configuration
  52 =============
  53
  54 Compact 3000
  55 ============
  56 Enable the debug port by activating
  57
  58 - Configuration
  59
  60   - Server configuration
  61
  62     -  D channel output via IP D channel output via IP on/off
  63
  64 German:
  65
  66 - Einrichtung
  67
  68   - Serverkonfiguration
  69
  70     - D-Kanal über IP ausgeben D-Kanal über IP ausgeben ein-/ausschalten
  71
  72
  73 Callnotifier
  74 ============
  75 Copy ``data/callnotifier.config.php.dist`` to ``data/callnotifier.config.php``
  76 (same name, just no ``.dist``), open it in a text editor and adjust it to
  77 your needs.
  78
  79 It contains examples for every plugin.
  80 Adjust them as you need and remove the ones you do not need.
  81
  82
  83
  84 Call types
  85 ==========
  86 Logging plugins allow you to specify when calls shall be logged:
  87
  88 - ``startingCall`` - when the call is coming in, and the telephone rings
  89 - ``finishedCall`` - when the call has ended
  90
  91 Furthermore you may decide which calls to log:
  92
  93 - ``i`` - Log incoming calls only
  94 - ``o`` - Log outgoing calls only
  95 - ``io`` - Log both incoming and outgoing calls
  96
  97
  98 =======
  99 Plugins
 100 =======
 101 There are two types of plugins: Detailler and Logger.
 102 Detaillers load additional details to a call - e.g. a name - and loggers
 103 can do anything, e.g. write a log file or send a XMPP message.
 104
 105 Detailler
 106 =========
 107 Plugins that fetch additional details to calls are named "detailler".
 108
 109 CallMonitor_Detailler_LDAP
 110 --------------------------
 111 The plugin determines the name for a telephone number by looking up a
 112 LDAP directory.
 113
 114 It retrieves the name of the caller for incoming calls, and the name
 115 of the telephonee for outgoing calls.
 116
 117 It searches the following LDAP attributes:
 118
 119 - ``companyPhone``
 120 - ``homePhone``
 121 - ``mobile``
 122 - ``otherPhone``
 123 - ``telephoneNumber``
 124
 125 Example configuration::
 126
 127     $callMonitor->addDetailler(
 128         new CallMonitor_Detailler_LDAP(
 129             array(
 130                 'host' => 'ldap.home.cweiske.de',
 131                 'basedn' => 'ou=adressbuch,dc=cweiske,dc=de',
 132                 'binddn' => 'cn=readonly,ou=users,dc=cweiske,dc=de',
 133                 'bindpw' => 'readonly'
 134             )
 135         )
 136     );
 137
 138
 139 CallMonitor_Detailler_OpenGeoDb
 140 -------------------------------
 141 The plugin determines the location (city) for a telephone number by
 142 checking the area code (prefix number) against a OpenGeoDB SQL database.
 143
 144 If several locations share the same area code, the one with the most inhabitants
 145 is used.
 146
 147 If you use this plugin, you need to run ``docs/opengeodb-create-my_orte.sql``
 148 on the OpenGeoDB database to create an indexed table with all relevant
 149 information needed by the plugin.
 150
 151 Example configuration::
 152
 153     $callMonitor->addDetailler(
 154         new CallMonitor_Detailler_OpenGeoDb(
 155             'mysql:host=dojo;dbname=opengeodb',
 156             'opengeodb-read',
 157             'opengeodb'
 158         )
 159     );
 160
 161
 162 Logger
 163 ======
 164 Logger handle react on events like incoming or outgoing calls,
 165 if they start or finish, or on any data received from the ISDN bus.
 166
 167 Available logger:
 168
 169 CallDb
 170   Log calls in a SQL database
 171 CallDreambox
 172   Send messages on incoming calls to the DreamBox satellite
 173   receiver
 174 CallEcho
 175   Log to the command line. Helpful for debugging.
 176 CallFile
 177   Log finished calls into a text file
 178 CallFileTop
 179   Log finished calls into a text file, newest on top
 180 CallNotifySend
 181   Use the unix ``notify-send`` command on starting and finished calls
 182 CallSendXmpp
 183   Send an XMPP headline message for incoming calls to one or multiple
 184   users.
 185
 186
 187 ============
 188 Known issues
 189 ============
 190 Ctrl+C does not send the disconnect command.
 191 This is a problem with PHP since pcntl_signal handling and blocking sockets
 192 do not work together. The signal will not be handled.
 193
 194
 195 =======
 196 License
 197 =======
 198 Auerswald callnotifier is licensed under the terms of the GPLv3 or later.
 199
 200
 201 ======
 202 Source
 203 ======
 204 Original git website: https://git.cweiske.de/auerswald-callnotifier.git
 205
 206 Mirror: https://github.com/cweiske/auerswald-callnotifier