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