git.defcon.no Git - hermes/blob - doc/README

   1 ABOUT HERMES
   2 ------------------------------------------------------
   3
   4 Hermes is a framework for managing a Kamailio SIP VoIP infrastructure.  It is
   5 designed to manage user accounts, SIP aliases, E164 phone number aliases and
   6 automatic provisioning of hardphones. Hermes provides an API as a foundation
   7 for its own user interface, and for integration with other systems. The API is
   8 implemented as HTTP-REST using JSON.  The user interface focuses on dayly
   9 administration tasks (user management, alias handling, phone registration) and
  10 not on Kamailio server management.
  11
  12 LICENSE
  13 ------------------------------------------------------
  14   Copyright (c) 2012, Gjøvik University College
  15   All rights reserved.
  16
  17   Redistribution and use in source and binary forms, with or without
  18   modification, are permitted provided that the following conditions are met:
  19       * Redistributions of source code must retain the above copyright
  20         notice, this list of conditions and the following disclaimer.
  21       * Redistributions in binary form must reproduce the above copyright
  22         notice, this list of conditions and the following disclaimer in the
  23         documentation and/or other materials provided with the distribution.
  24       * Neither the name of the Gjøvik University College nor the
  25         names of its contributors may be used to endorse or promote products
  26         derived from this software without specific prior written permission.
  27
  28   THIS SOFTWARE IS PROVIDED BY Gjøvik University College ''AS IS'' AND ANY
  29   EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  30   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31   DISCLAIMED. IN NO EVENT SHALL Gjøvik University College BE LIABLE FOR ANY
  32   DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  33   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  34   LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  35   ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  36   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  37   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38
  39
  40 CONFIGURING THE FRONTEND/UI
  41 ------------------------------------------------------
  42 TBD
  43
  44 DATABASE PREREQUESTITES FOR THE API
  45 ------------------------------------------------------
  46
  47 Hermes expects that Kamailio is installed and configured to use MySQL backing,
  48 with teh Siremis SQL structure, with subscribers in a 'subscribers' table, and
  49 aliases stored in 'dbaliases'. An SQL structure script for the tables used by
  50 Hermes is included in doc/sql-data/structure-kamailio.sql That file is included
  51 as a guide to verify the Kamailio configuration, and as a structure to use in
  52 development/testing as a replacement for a real Kamailio installation.
  53
  54 Hermes itself requires a MySQL database on the same MySQL server, with the
  55 structure defined in doc/sql-data/structure-hermes.sql
  56 A database must be created, and the structure loaded prior to configuring
  57 the API.
  58
  59
  60 You may also choose to load the sample data. Note that the sample data does
  61 include a R/W API key, tied to the host 10.0.2.5. Replacing the IP
  62 address of that key may be used to boot-strap authorizations...
  63
  64 CONFIGURING THE API
  65 ------------------------------------------------------
  66
  67 The API needs to be configured separately from the UI.
  68 API configuration is done by creating the PHP file
  69 $install_path/api/config.php. A sample configuration file
  70 is provided as $install_path/api/config.php.sample.
  71 If config.php is not present, the API may fail in
  72 in somewhat unpredictable ways ...
  73
  74 sql_server      -> Your MySQL server ...
  75 sql_username    -> Username for MySQL access
  76                 Needs RW access to kamailio and provision db's
  77 sql_password    -> Password for the above username
  78 kamailio_db     -> Database name of kamailio db.
  79 hermes_db       -> Database name of hermes db.
  80
  81 The following configuration options define SQL table names
  82 for respective data-sets, values for the sample-data.sql
  83 are listed... :
  84
  85 kamailio_domain_table           (domain)
  86 kamailio_subscriber_table       (subscriber)
  87 kamailio_alias_table            (dbaliases)
  88 kamailio_domain_table           (domain)
  89 hermes_users_table              (users)
  90 hermes_phones_table             (phones)
  91 hermes_servers_table            (servers)
  92 numbers_table                   (numbers)
  93 apikeys_table                   (apikeys)
  94 authorizations_table            (authorizations)
  95 sessionkeys_table               (sessionkeys)
  96
  97 Configuration parameters not related to database:
  98
  99 auth_backend
 100  -> Backing store plugin for API user auth.
 101
 102 sessionkey_lifetime
 103  -> The amount of time an auth_key is valid in an API session.
 104     Aka max ping-interval.
 105
 106 standard_dialplan
 107  -> Dialling pattern to use for new users
 108
 109 default_domain
 110  -> What domain should always be listed first
 111
 112 permit_multiple_e164alias -
 113  -> Currently not used ...
 114
 115