LMS - LAN Management System 1.8.0rc5 Rosha

   [logo-small.png]

LMS Developers

   Copyright  2001-2005 LMS Developers
     _________________________________________________________________

   Table of Contents
   1. Intro

        1.1. About LMS
        1.2. Authors
        1.3. Legal Notice
        1.4. Other Information

   2. Installation and configuration

        2.1. Intro
        2.2. Requirements
        2.3. LMS Installation
        2.4. Localization
        2.5. Database Server Installation
        2.6. Basic Configuration
        2.7. Access rights
        2.8. Upgrade
        2.9. Documents

   3. User Interface (LMS-UI)

        3.1. Login
        3.2. Administration
        3.3. Customers
        3.4. Nodes
        3.5. Net Devices
        3.6. IP Networks
        3.7. Finances
        3.8. Accounts
        3.9. Mailing
        3.10. Reload
        3.11. Stats
        3.12. Helpdesk
        3.13. Timetable
        3.14. Configuration

   4. Scripts

        4.1. Installation
        4.2. List of available scripts
        4.3. Description and configuration

   5. Configuration file generator (lms-mgc)

        5.1. Installation
        5.2. Configuration
        5.3. Examples of use

   6. LMS Daemon

        6.1. Basics
        6.2. Modules
        6.3. T-Script

   7. For curious

        7.1. Directory tree
        7.2. Database structure
        7.3. Configuration file format
        7.4. Filling DB with random data
        7.5. Access levels
        7.6. Restrictions

   8. Extensions

        8.1. Customer account
        8.2. Customer account 2
        8.3. SQL Panel
        8.4. Squid redirector

   9. FAQ

   List of Tables
   4-1. Executable scripts list
   6-1. List of all lmsd modules
   7-1. LMS directory tree

   List of Examples
   3-1. Accounts. Proftpd configuration.
   3-2. Accounts. Mail server configuration (postfix+sasl+courier).
   4-1. Lms-notify: example of last 10 customer's operations
   4-2. Lms-notify: example of mailing template
   5-1. Lms-mgc: Example instance
   6-1. Parser: Creating /etc/hosts file
   6-2. Parser: Debtors list
   6-3. Parser: Ethernet hosts descriptions for iptraf.
   6-4. Parser: Ethers file for arp
   6-5. Parser: Notify module replacement
   6-6. Parser: Traffic stats.
   7-1. Format of configuration options
     _________________________________________________________________

Chapter 1. Intro

1.1. About LMS

   LMS  (LAN Management System) is a package of applications for managing
   LAN  networks.  Its  main  goal  is  to  provide  the  best service to
   customers, as seen in large ISP companies. LMS is written in PHP, Perl
   and  C  and  can use MySQL or PostgreSQL as its database backends. The
   following functionalities are provided at the time:
     * customer database (names, addresses, phones, comments, etc),
     * computers inventory (IP, MAC),
     * simple financial system suited for network operations,
     * financial balances and invoices,
     * email warnings to users,
     * automatic billing schedule,
     * ability  to  generate  (almost)  any  kind  of  config  file  (ie.
       ipchains/iptables  firewall  scripts,  DHCP  daemon configuration,
       zones for bind, /etc/ethers entries, oident, htb and more...),
     * visualization of bandwidth consumption per host,
     * request tracker system (Helpdesk),
     * timetable (Organizer).

   Initial   components   of   this   software   were   invented  to  aid
   administration  of  ASK NetX (amateur computer network) and it's still
   developed and tested here.

   LMS   won't   replace  administration  skills.  If  you  can't  handle
   installation and configuration of your system, you likely won't manage
   to  adjust  LMS  for  your  system.  In short - administration of UNIX
   systems is needed to operate this software.
     _________________________________________________________________

1.2. Authors

1.2.1. LMS Developers

     * PHP Code:

       Lukasz 'Baseciq' Mozer
       Michal 'DziQs' Zapalski
       Radoslaw 'Warden' Antoniuk
       Krzysztof 'hunter' Drewicz
       Marcin 'Lexx' Krol
       Aleksander 'A.L.E.C' Machniak
       Konrad 'kondi' Rzentarzewski
     * C Code:

       Aleksander 'A.L.E.C' Machniak
       Marcin 'Lexx' Krol
     * Perl Code:

       Lukasz 'Baseciq' Mozer
       Michal 'DziQs' Zapalski
       Maciej 'agaran' Pijanka
       Krzysztof 'hunter' Drewicz
     * Design:

       Lukasz 'Baseciq' Mozer
     * HTML, JavaScript, CSS:

       Lukasz 'Baseciq' Mozer
       Pawel 'Bob_R' Czerski
       Pawel 'sickone' Kisiela
       Konrad 'kondi' Rzentarzewski
     * Images:

       Piotr 'Pierzak' M.
       Grzegorz 'byko' Cichowski
       Kuba 'kflis' Flis
       Lukasz 'Baseciq' Mozer
       Jakub 'Jimmac' Steiner
     * MySQL Support:

       Kuba 'shasta' Jankowski
       Radoslaw 'Warden' Antoniuk
       Przemyslaw Babinski
     * PostgreSQL Support:

       Aleksander 'A.L.E.C' Machniak
     * Web Page & Documentation:

       Aleksander 'A.L.E.C' Machniak
       Kuba 'shasta' Jankowski
       Grzegorz 'JaBBaS' Dziegielewski
       Lukasz 'Baseciq' Mozer
       Marcin 'Lexx' Krol
       Konrad 'kondi' Rzentarzewski
     * Beta testing:

       Grzegorz 'byko' Cichowski
       Radoslaw 'Warden' Antoniuk
       Tomasz 'dzwonek' Dzwonkowski
       Sebastian 'Victus' Frasunkiewicz
       Kuba 'kflis' Flis
       Krystian 'UFOczek' Kochanowski
       Grzegorz 'JaBBaS' Dziegielewski
       Andrzej 'chsh' Gradziel
     _________________________________________________________________

1.2.2. Others

   LMS   uses   elements   of  other  software:  phpMyAdmin,  phpsysinfo,
   NewsPortal,   overLIB,   ezpdf,   Tigra   Calendar,   Piotr   Kleban's
   number-to-words  conversion  procedures  and  code  examples  from PHP
   manual.
     _________________________________________________________________

1.3. Legal Notice

   This  program  is free software; you can redistribute it and/or modify
   it  under  the terms of the GNU General Public License as published by
   the  Free Software Foundation; either version 2 of the License, or (at
   you option) any later version.

   This  program  is  distributed in the hope that it will be useful, but
   WITHOUT   ANY   WARRANTY;   without   even  the  implied  warranty  of
   MERCHANTABILITY  or  FITNESS  FOR  A  PARTICULAR  PURPOSE. See the GNU
   General Public License for more details.

   You  should  have  received  a  copy of the GNU General Public License
   along   with  this  program;  if  not,  write  to  the  Free  Software
   Foundation,  Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
   USA.

   Text of License is here.
     _________________________________________________________________

1.4. Other Information

1.4.1. Contact

   Preferably  via  a  mailing  list,  which you can subscribe by sending
   empty    e-mail   with   subject   "subscribe   lms-en"   to   address
   ecartis@lists.rulez.pl.  Further  emails  should  be  sent  to address
   lms-en@lists.rulez.pl.
     _________________________________________________________________

1.4.2. Ideas and Bugs Reports

   In  order to effectively report bugs or new ideas, it's recommended to
   subscribe  mailing  list, where you can get quickest response for your
   problems  from  either  LMS users or developers team. There's also Bug
   Tracking System available, when you can report bugs upon registration.
   Reports  from  BTS  are  also  forwarded  to mailing list, so the best
   practice  is  to  subscribe  to  list, report via BTS and send link to
   mailing  list and finally wait as your report will evolve. BTS address
   is bts.rulez.pl.
     _________________________________________________________________

1.4.3. Newest version

   Newest  version of LMS can be downloaded from CVS repository utilizing
   WWW  interface  at  cvs.rulez.pl, or with CVS tools (anonymous access,
   empty password):
cvs -d :pserver:cvs@cvs.rulez.pl:/home/cvsroot login
cvs -d :pserver:cvs@cvs.rulez.pl:/home/cvsroot co lms
cvs -d :pserver:cvs@cvs.rulez.pl:/home/cvsroot logout
     _________________________________________________________________

1.4.4. Changelog

   Informations  about  changes and version history of LMS is included in
   Changelog.
     _________________________________________________________________

1.4.5. Commercial Support

   There  are questions appearing periodically on lms mailing lists about
   adding  some  funtions  to  LMS. Matter of payment for support is very
   difficult.  Note,  that  there  is  no  company  behind  LMS,  so  any
   commercial  adoption  or  support should be discussed directly between
   You  and  involved  developer.  You  are  reading  english  version of
   documentation,  it's  likely that you are not from Poland, which makes
   even simple things like issuing invoice or money transfer complex. The
   most experienced developer in that matter is Alec. You can see details
   on support on his page: http://lms.alec.pl/index.php?lang=en
     _________________________________________________________________

Chapter 2. Installation and configuration

2.1. Intro

   LMS  consist  a  few  modules.  LMS-UI  is  user  interface,  which is
   responsible  for  all  interactions with user, entirely written in PHP
   and  it  uses  SQL  database  to  store  all  data,  thus  PHP  script
   interpreter and SQL engine of your choice (MySQL or Postgresql).

   LMS  also  contains  a  set  of  Perl scripts, responsible for various
   operations,  ie.  periodically  applying  subscription fees or sending
   reminders  to  users  who are in debt. It also contains LMS-MGC, which
   may  be  configured  to  generate  virtually any configuration file or
   script  and  manage  your  server. Note that some of the scripts might
   need additional Perl modules to function.

   At the end there is also LMS Daemon, written in C, which is being used
   (its  plugins  in  fact)  as  a  drop-in  replacement for LMS-MGC - to
   configure  and manage (ie. restart) your services. It's main advantage
   is that it responds for all LMS-UI changes in realtime.
     _________________________________________________________________

2.2. Requirements

2.2.1. Web Server

   Because  LMS-UI is written in PHP, it needs Web server to work. Apache
   is preferred (www.apache.org).
     _________________________________________________________________

2.2.2. PHP Interpreter

   Interpreter  version  should be 4.2.x or higher. PHP can be downloaded
   from www.php.net. At least following PHP modules needs to be installed
   (look for "extension" in php.ini or in output of phpinfo function):
     * pcre, posix,
     * zlib (for compressed backups),
     * gd or ming (for network map),
     * mysql or pgsql (for db support),
     * iconv (for pdf printouts and latin-utf conversion),
     * PEAR::Mail  (which  require  PEAR::Net_SMTP and PEAR::Net_Sockets)
       for mailing.
     _________________________________________________________________

2.2.3. Database Server

   MySQL  server  in  version  3.23.xx and higher is supported. LMS won't
   work correctly with older versions.

   PostgreSQL in version 7.3.x or higher is supported.
     _________________________________________________________________

2.2.4. Smarty Library

   LMS-UI  requires  Smarty  library  (http://smarty.php.net)  in version
   2.6.0  or  higher  (don't use 2.6.4 version). Newer versions of Smarty
   requires that you have not enabled "magic_quotes_runtime" (set to Off)
   option in PHP configuration.
     _________________________________________________________________

2.2.5. Perl

   LMS-MGC  and  the  rest of Perl scripts requires also Perl interpreter
   and some modules:
     * Perl and its basic modules (POSIX, GetOpt::Long),
     * Config::IniFiles,
     * DBI,
     * DBD-mysql (if you use MySQL),
     * DBD-Pg (if you use Postgres),
     _________________________________________________________________

2.2.6. C Compiler

   If  you  intend  to  run  LMS Daemon you will need working C compiler,
   because daemon will be provided in source code form only.
     _________________________________________________________________

2.2.7. Web Browser

   LMS has web user interface, so you'll need web browser with javascript
   and cookies enabled. Our exparience says that Mozilla Firefox 1.x will
   be a good choice.
     _________________________________________________________________

2.3. LMS Installation

   LMS  in  tarball (.tar.gz) archive can be downloaded from project home
   page  (lms.rulez.pl),  which  should be extracted and placed in chosen
   directory  (i.e.  /var/www/lms) and made available for Web Server (ie.
   with Alias /lms/ /var/www/lms):
$ cd /var/www
$ wget http://lms.rulez.pl/download/stable/lms-x.x.x.tar.gz
$ tar zxf lms-x.x.x.tar.gz

   Two  kind  of  LMS packets are available - the one with Smarty library
   included (lms-x.x.x+libs.tar.gz) and without this library. If you have
   installed version without library you have to get Smarty yourself (eg.
   using PEAR) and place it in lib subdirectory.
$ cd /var/www/lms/lib
$ wget http://smarty.php.net/distributions/Smarty-2.6.0.tar.gz
$ tar zxf Smarty-2.6.0.tar.gz
$ mv Smarty-2.6.0/libs Smarty

   Note

        Location of all directories can be set in [directories] section in
        lms.ini configuration file.

   Configuration  files (sample/lms.ini and sample/lms-mgc.ini) should be
   placed in /etc/lms directory.

   Scripts  from bin directory should be moved to /usr/sbin directory, so
   you can execute it directly without giving path.

 Warning

         Web Server must have read permission on lms.ini file and write
         permission on backup directory. Please consider security implications:
         you might want to protect backup directory with .htaccess and place
         your lms.ini outside Web Server's DocumentRoot (LMS allows you to
         place it in its home directory, but then it's possible to read it with
         http://yourserver/lms.ini, and it contains valuable information such
         as database password!).
     _________________________________________________________________

2.4. Localization

   Default language of user interface is English, and national characters
   are  encoded  in  UTF-8.  For proper display of national characters in
   other  languages  you must define appropriate locales. E.g. for polish
   language it's achieved by running the following command:
# localedef -v -c -i pl_PL -f UTF-8 /usr/share/locale/pl_PL.UTF-8

   Instructions  about  database  encoding  settings in follow-up of this
   chapter.
     _________________________________________________________________

2.5. Database Server Installation

2.5.1. MySQL

2.5.1.1. Intro

   That  very popular database server is available with majority of Linux
   distributions.  If,  however,  you  have to install it yourself, start
   with downloading its sources from www.mysql.com.
     _________________________________________________________________

2.5.1.2. MySQL Server Installation

   After extracting, go to directory with MySQL and type this sequence of
   commands:
$ ./configure --prefix=/usr/local/mysql
$ make
$ make install
$ /usr/local/mysql/bin/mysql_install_db
$ chown mysql -R /usr/local/mysql/var
$ /usr/local/mysql/bin/safe_mysqld &
$ /usr/local/mysql/bin/mysqladmin -u root password new_password
     _________________________________________________________________

2.5.1.3. Create Database

   You  have to create database if you run LMS for the first time. If you
   are  upgrading from older version, look into Changelog for appropriate
   notes  about database changes. In order to create database and load it
   with schema go to LMS directory and run:
mysql -u[user name with database creation rights] -p
Enter password:[just enter password :)]
mysql> CREATE DATABASE lms /*!40101 CHARACTER SET utf8 COLLATE utf8_polish_ci */;
mysql> GRANT USAGE ON lms.* TO lms@localhost;
mysql> GRANT select,insert,update,delete,create,alter,drop ON lms.* TO lms@localhost IDENTIFIED BY '[your_password]';
mysql> flush privileges;
mysql> use lms;
mysql> source doc/lms.mysql;
     _________________________________________________________________

2.5.1.4. LMS Configuration (lms.ini)

   Because MySQL is default database for LMS, configuration is limited to
   [database]  section  setup. Thus you need to edit /etc/lms/lms.ini and
   fill in password and user's name:
user     = lms
password = your_password

   After  this  step  you should be able to enter your system without any
   problems.  Just  write an URL for your LMS installation. If there's no
   user account (first run), you'll be prompted with form to add username
   and  some personal data. When you enter correct admin personal details
   LMS  will  move  you  to  login  page, where you can use newly created
   account.

   Let's stop here and add some stuff to cron, for peace of mind:
12 4 3,10,17,21,28 * * /usr/bin/mysqldump -u lms --password=your-super-secret-password \
              --add-drop-table --add-locks lms > backups/lms-auto-"$(date +%s)".sql

   That  will  create mysql database backup automagically each 3, 10, 17,
   21 and 28 day of month at 4:12 at night.
     _________________________________________________________________

2.5.2. PostgreSQL

2.5.2.1. Intro

   LMS  is  tested  on  PostgreSQL  7.3.4 and higher, but because none of
   special  features  of  the  engine  are  ever used, there should be no
   problems with its later versions. If you have not installed PostgreSQL
   server, best solution is to compile it yourself from sources available
   on www.postgresql.org.
     _________________________________________________________________

2.5.2.2. Installation

   That  is  a  short version of installation procedure, more info can be
   found  in  Postgres  documentation.  After  you  download  and extract
   sources go to main directory and run following commands:
$ ./configure --enable-locale
$ gmake
$ su
$ gmake install
$ adduser postgres
$ mkdir /usr/local/pgsql/data
$ chown postgres /usr/local/pgsql/data
$ su - postgres
$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data --locale=pl_PL.UTF-8
$ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
     _________________________________________________________________

2.5.2.3. Database Creation

   While  server  is  running  you can start with adding database and its
   owner, both named 'lms' and loading database schema:
$ /usr/local/pgsql/bin/createuser -d -A -P lms
$ /usr/local/pgsql/bin/createdb -E UNICODE -U lms lms
$ /usr/local/pgsql/bin/psql -d lms -U lms -f /lms/doc/lms.pgsql
     _________________________________________________________________

2.5.2.4. LMS Configuration (lms.ini)

   For  LMS default database server is MySQL so you have to set following
   options in [database] section of /etc/lms/lms.ini file:
type     = postgres
user     = lms
password = password_entered_with_lms_user_creation

   Note

        The need for password actually depends on Postgres users
        authentication configuration found in
        /usr/local/pgsql/data/pg_hba.conf (refer to Postgresql documentation).
        By default password is not required and you can comment it with
        semicolon.

   After  this  step  you should be able to enter your system without any
   problems.  Just  write an URL for your LMS installation. If there's no
   user account (first run), you'll be prompted with form to add username
   and  some personal data. When you enter correct admin personal details
   LMS  will  move  you  to  login  page, where you can use newly created
   account.

   Let's stop here and add some stuff to cron, for peace of mind:
12 4 3,10,17,21,28 * * /usr/bin/pg_dump -U lms --clean \
                    lms --file=backups/lms-auto-"$(date +%s)".sql
     _________________________________________________________________

2.6. Basic Configuration

   Main  configuration  file  of  LMS is lms.ini, which must be placed in
   directory  /etc/lms  or  in  LMS  root directory (not recommended, see
   Section  2.3!!!). It contains configuration options for LMS-UI and for
   all scripts with exception of LMS-MGC.

   Note

        Remember to remove semicolons (comments sign) from beginning of line
        with parameter that you set.

   Note

        As of version 1.6 and later storing config in lms.ini is beeing
        treaded as obsolete. The only required values there are from
        [database] and [directories] sections. Settings are stored in database
        and could be changed by user interface.
     _________________________________________________________________

2.6.1. Section [database] - Database Settings

     * type
       Database  type.  Currently  in  100%  are  supported  'mysql'  and
       'postgres'. Default: mysql
       Example: type = mysql
     * host
       Host  where  database is running. Usually 'localhost', but you can
       set   anything   here   (IP,   domain   or   path   to  socket  in
       'localhost:/path/to/socket' format). Default: localhost
       Example: host = localhost
     * user
       Database  user  account  name.  In  many cases (if you follow this
       documentation)  that  will be 'lms'. If you want to use privileged
       account,  you  can enter 'root' (MySQL on most of *nixes), 'mysql'
       (on PLD) or 'postgres' (PostgreSQL). Default: mysql
       Example: user = lms
     * password
       Database user password. Default: empty.
       Example: password = password
     * database
       Database name. Default: lms
       Example: database = lms
     * server_encoding
       Database  encoding.  Use if your database encoding is not Unicode.
       Postgres  is  performing  conversion automatically, but if you use
       MySQL PHP and iconv in LMS DB drivers is used. Default: unicode
       Example: server_encoding = latin2
     _________________________________________________________________

2.6.2. Section [directories] - Directories Settings

     * sys_dir
       System directory. It is a place where the entire content of LMS UI
       is placed, that means index.php, graphics, templates and the rest.
       By  default  index.php  tries  to  guess where is it located using
       getcwd(), but it's better to say it where it is:
       Example: sys_dir = /var/www/htdocs/lms/
     * modules_dir
       Directory   with  LMS  "modules".  That  is  content  of  /modules
       directory. By default it is modules subdirectory of sys_dir.
       Example: modules_dir = /usr/share/lms/modules/
     * lib_dir
       Directory with LMS "libraries". That is content of /lib directory.
       By default it is lib subdirectory of sys_dir.
       Example: lib_dir = /usr/share/lms/lib/
     * backup_dir
       Directory  for  database backup files - it's a place where LMS can
       write   its   database   snapshots.   By  default  it  is  backups
       subdirectory of sys_dir.
       Example: backup_dir = /var/backup/lms/

  Warning

          If directory with backups is accessible from WWW level (within Web
          Server DocumentRoot), anybody can access them without authentication.
     * doc_dir
       Directory for documents archive - it's a place where LMS can write
       uploaded  files.  By  default  it  is  documents  subdirectory  of
       sys_dir.
       Example: doc_dir = /usr/share/lms/docs/

      Warning

              If that directory is accessible from WWW level (within Web Server
              DocumentRoot), anybody can access them without authentication.
     * smarty_dir
       Directory  with Smarty library - By default Smarty subdirectory of
       lib_dir.
       Example: smarty_dir = /usr/lib/php/Smarty
     * smarty_compile_dir
       Compilation  directory  for  Smarty.  It's  a  place  where Smarty
       compile  its  templates. By default it is templates_c subdirectory
       of sys_dir.
       Example: smarty_compile_dir = /var/smarty/compile/lms
     * smarty_templates_dir
       Directory  with  templates  for Smarty. By default it is templates
       subdirectory of sys_dir.
       Example: smarty_templates_dir = /usr/share/lms/templates
     _________________________________________________________________

2.6.3. Section [finances] - Finances Settings

   This  section  consist  options  for  financial system and for payment
   forms. You can read more about that in chapter 'Documents'.
     * suspension_percentage (optional)
       Percentage for suspended liabilities. Default: '0'
       Example: suspension_percentage = '50'
     _________________________________________________________________

2.7. Access rights

2.7.1. Idea

   In  LMS  you may define up to 256 rules to access the system. Each can
   permit  or  deny  access  to  defined  modules. Each user can have any
   combination of access rules assigned to his account.

   By default following access rules list is defined:
     * full access
     * read only (excluding Helpdesk)
     * nodes connection/disconnection
     * finances management
     * configuration reload
     * customers management
     * nodes management
     * stats access
     * mailing access
     * Helpdesk (RT) administration
     * Helpdesk (RT) operation
     * accounts management
     * configuration
     * networks and devices management
     * timetable management
     * daemon management and configuration
     * users edition and addition forbidden
     * no access

   Most of them grant access to modules and two denies. Modules that user
   has always access are: welcome, copyrights, logout, chpasswd (chpasswd
   can  change  only  own  password),  access to all others is defined by
   rules.
   Note

        If you don't define any access rule for user, then LMS defines 0 rule
        for him, which mean: full access.
     _________________________________________________________________

2.7.2. How does it work?

   Algorithm  that decides whether user has access to given module or not
   is as following:
   - First of all: checking list of modules that user always has access.
   - Next: checking if module match rules in each levels user has access
   to.
   - Finally: Decision if user is permitted to access modules. If module
   match to any level that denies access then access will be forbidden
   even if user has level that permits access to module. For example, if
   someone has full access and no access to "add computer" module, then
   he won't able to access module. If module matches level that permits
   access to module, then LMS will grant access to module, but if module
   does not match at any level then no-access-message also will be
   printed.
     _________________________________________________________________

2.7.3. User-defined access rules

   Advanced  users  can  define  any  additional access rules or redefine
   existing  ones.  In order to do that you must make PHP script based on
   file lib/accesstable.php and place it in LMS's lib directory. Then set
   option custom_accesstable in [phpui] section to created file name.

   In  that  way  it's possible to define your own rules to allow or deny
   access  for  any  modules.  Module  is  a  name of PHP file in modules
   directory,  given without extension in access rules. For example, it's
   possible   to   define   rule   for   invoices   display   (e.g.   for
   lms-sendinvoices script) in the following way:
<?php
$access['table'][100]['name']      = 'invoices display';
$access['table'][100]['allow_reg'] = '^invoice$';
?>
     _________________________________________________________________

2.8. Upgrade

   Since  version  1.5.4 LMS was released in polish language only. If you
   are  upgrading  read  polish documentation for upgrade description. In
   newest  versions  upgrade  is  very easy. That process has two stages.
   First,  overwrite  old  files  with  new  ones  and remove contents of
   templates_c  directory  (or  better  create  new  LMS directory tree).
   Second  stage  is  a  database  structure change - it's self-executing
   process acting upon first login to the UI.
     _________________________________________________________________

2.9. Documents

   LMS  makes  possible  to  generate and to store various documents i.e.
   invoices,   receipts   and  non-financial  documents  i.e.  contracts,
   protocols  and  others. Documents can be numbered with numbering plans
   (patterns) defined in menu Configuration - Numbering Plans.
     _________________________________________________________________

2.9.1. Invoices

   It's  possible  to  issue  invoices in either automatic or manual way.
   Manual  invoices  creation  is  possible  in 'New Invoice' module from
   'Finances' menu. Automatic issue might be helpful while you have legal
   contracts  with  your  users.  In  this  case  invoices are created by
   lms-payments script or lmsd daemon.

   For  proper  work  of  printouts  you  need to setup custom options in
   configuration section [invoices]:
     * header
       Seller. Can use string "\n" for lines separation. Default: empty.
       Example: header = "SuperNet ISP\nNew Street 15\n12-000 City\n"
     * footer
       Invoice  footer  -  e.g.  contact information about seller. Footer
       will  be placed at bottom of an invoice, using small font. Like in
       header option use "\n" to separate lines. Default: empty
       Example:   footer   =   "Internet  Service  Provider  K-27,  phone
       555-23-23, etc."
     * default_author
       Invoice issuer name. Default: empty
       Example: default_author = "invoicing expert"
     * cplace
       Invoice issue location (city). Default: empty.
       Example: cplace = Warsaw
     * print_balance_history
       If  true  on  invoice  (html) will be printed history of financial
       operations on customer account. Default: not set.
       Example: print_balance_history = true
     * print_balance_history_limit
       Records number on customer balance list on invoice. Specify last x
       records. Default: 10.
       Example: print_balance_history_limit = 20000

   Generated  invoices  can be viewed in two ways: by clicking on printer
   icon,  in  balance  sheet  page  or  by  clicking  'Invoices  List' in
   'Finances'  menu.  In second case, is also possible to filter invoices
   for printing.
     _________________________________________________________________

2.9.1.1. HTML

   Invoices  are  printed  in  html  format  by  default  using  provided
   template. In [invoices] section you can also configure:
     * template_file
       Invoice  template,  which should be placed in templates directory.
       Default: invoice.html.
       Example: template_file = invoice-mynet.html
     * content_type
       Invoice content-type. If you enter here 'application/octet-stream'
       then  browser will ask to save file on disk, instead of displaying
       it.  It's  useful  if you use your own template which generate eg.
       rtf or xls file. Default: 'text/html'
       Example: content_type = application/octet-stream
     * attachment_name
       File  name  for saving finished invoice printout. WARNING: Setting
       attachment_name  with  default content_type will (in case of MSIE)
       print  invoice  +  prompt  for  save on disk + bonus browser crash
       (6.0SP1 on WInXP). Default: empty.
       Example: attachment_name = invoice.xls

   Generated  invoice  in  HTML  format  consist of originals and copies,
   which are separated by CSS page-break markups, so every modern browser
   that  supports  CSS  should  print  many-page invoices correctly. This
   behavior was tested on Microsoft Internet Explorer 6.0, Opera 7.02 and
   Mozilla 1.3.

   Note

        Almost every internet browser has printing configuration, where
        functions like header and footer or URL printing can be disabled.
     _________________________________________________________________

2.9.1.2. PDF

   It's  possible to create invoices as PDF files. Setting option type in
   [invoices]  section  to  'pdf' will force invoice being created in PDF
   instead  of  html. Option template_file has the same meaning, with one
   difference,  that  it might take predefined values: 'standard' - basic
   invoice (invoice.html equivalent) and 'FT-0100' - invoice adjusted for
   printing  on  FT-0100  paper  including  payment  form.  You  can  set
   template_file  option for php file name, but this feature is meant for
   advanced  users as it requires you to create more complicated php file
   than the one used with html invoices Smarty template.
     _________________________________________________________________

2.9.1.3. Credit Notes

   Credit  notes  uses invoices settings from [invoices] section. Default
   invoice  template  include  also  credit  notes contents, but you have
   possibility to define different template for credit notes (the rest of
   options is common for both invoices and credit notes):
     * cnote_template_file
       Credit   note  template,  which  should  be  placed  in  templates
       directory. Default: invoice.html.
       Example: cnote_template_file = invoice-mynet.html
     _________________________________________________________________

2.9.2. Transfer forms

   Transfer  forms  it's  Polish  specific feature. Data for payment form
   printouts is stored in [finances] configuration section. That is:
   name - seller name
   shortname - short seller name
   address - seller address
   zip - seller postal code
   city - seller city
   account - banking account number
   pay_title - title of payment
     _________________________________________________________________

2.9.3. Cash Receipts
     _________________________________________________________________

2.9.3.1. HTML

   Receipts  are  printed  in  html  format  by  default  using  provided
   template. In [receipts] section you can also configure:
     * template_file
       Cash  receipt  template,  which  should  be  placed  in  templates
       directory. Default: receipt.html.
       Example: template_file = /mytemplates/receipt.html
     * content_type
       Printout content-type. If you enter here
       'application/octet-stream'  then  browser will ask to save file on
       disk,  instead  of  displaying it. It's useful if you use your own
       template which generate eg. rtf or xls file. Default: 'text/html'
       Example: content_type = application/octet-stream
     * attachment_name
       File   name   for   saving   receipt  printout.  WARNING:  Setting
       attachment_name  with  default content_type will (in case of MSIE)
       print  document  +  prompt  for save on disk + bonus browser crash
       (6.0SP1 on WinXP). Default: empty.
       Example: attachment_name = receipt.xls
     _________________________________________________________________

2.9.3.2. PDF

   It's  possible to create receipts as PDF files. Setting option type in
   [receipts]  section  to 'pdf' will force document being created in PDF
   instead  of  html. Option template_file has the same meaning, with one
   difference,  that  it  might take predefined value: 'standard' - basic
   receipt  (receipt.html equivalent). template_file option can be set to
   PHP  file  name,  but  this  feature is meant for advanced users as it
   requires  you  to create more complicated PHP script than the one used
   with html receipts Smarty template.
     _________________________________________________________________

2.9.4. Other documents

   Documents  support  is  not  limited  to  invoices.  You  might  store
   virtually any documents you want in LMS, such as contracts, protocols,
   annexes  and  others.  You  can assign any number of documents to each
   customer  in 'Customer documents' tab in 'Customer information' panel.
   Each  document  should  have  defined title, type and additionally you
   might  define  it's  time  span  (time  until  when  it's  valid)  and
   description.  Document  files  are  being  stored  outside of database
   (which  should  be  kept  in  mind  while doing backups!) in directory
   defined with doc_dir in [directories] section of config file.

   Documents  can  be  uploaded  to  system  as  prepared files, but also
   generated  from  templates  with  use  of defined wizards. Here system
   gives     great     configuration    possibilities.    In    directory
   documents/templates/default  you  can  find  default  document  wizard
   (template  and  engine).  You  can  create  unlimited  number  of  own
   documents  wizards,  which  must  be  placed  in  documents/templates/
   directory.

   Each wizard must have file info.php with specified structure:
<?php
$engine = array(
    'name' => 'default',        // wizard (directory) name, lower case lettersand numbers
    'engine' => 'default',      // engine directory (engine.php)
    'template' => 'template.html',              // template file (in 'name' directory)
    'title' => trans('Default document'),       // description for LMS-UI
    'content_type' => 'text/html',              // output file type
    'output' => 'default.html',                         // output file name
)
?>

   File  info.php  define wizard and is required. To generate document is
   needed  engine  (file with name engine.php). You can create own engine
   or  use other by setting 'engine' variable to appropriate wizard name.
   So,  there  is no need to create engine for each new wizard. Is enough
   to make 'template' template and file info.php.
     _________________________________________________________________

Chapter 3. User Interface (LMS-UI)

   LMS User Interface is basically administration panel available via Web
   interface that can be used to create and manage customer and computers
   (nodes)  data and containing numerous features such as: You're able to
   bind  computer  data to your customers and assign it to given network.
   You're  also  able to define users liabilities and manage your network
   finances.  You can search in user and computer data quickly, send mass
   mailing to specific user groups, define access to this UI for selected
   users  and with fine grained access rights. Additionally you can track
   your  bandwidth  usability statistics, create backups of your database
   online  and  configuration  and management of your services. Those are
   only  selected  features  of LMS-UI, so read on to find description of
   all features.
     _________________________________________________________________

3.1. Login

   After  you  enter  LMS installation URL in your Web browser, you'll be
   prompted  with  login screen, where you need to enter correct username
   and password. All passwords in database are stored in encrypted form.

   If  it's  your  first session with LMS, and you don't have any account
   created  yet, you'll be redirected to new user account screen. At this
   moment you have only access to this one module, so that you can create
   your initial account.
     _________________________________________________________________

3.2. Administration

   After  successful  login to the system you'll have administration menu
   presented  on  the left side, while content of selected module will be
   displayed  on  the  right  side.  Initially,  you can read some useful
   information  about system here. In administration menu, you're able to
   manage other users accounts and create or restore database backups.

   You  can  select  any module to work with on the left panel. There are
   also  buttons  allowing  you  to  change your password, logout or do a
   quick  search for customers/computers/helpdesk. You can search by name
   or  id,  but  also additionally by computer name, surname, fragment of
   address,  phone, email, IP or MAC. If there are more than one matching
   record for your search you'll get only first result.
     _________________________________________________________________

3.2.1. Info

   This  is  where all basic information about system that is running LMS
   are  displayed.  It  lists  the  following  information:  LMS core and
   components  versions,  copyright  notice, uptime and kernel version of
   your  server, customers and nodes totals, computer activity totals and
   financial balance. Additionally all LMS links are gathered here.
     _________________________________________________________________

3.2.2. Users

   'Users'  panel  is designed for LMS users (ie. network administrators)
   management. You can create or modify any account here, change assigned
   passwords and access rights.

   For more information on access rights, see Section 2.7.

   Initially  after  selecting 'Users', you'll get list of all users with
   last  login  time and host information. When you click on the account,
   you're  able to see it's details, including defined access rights. You
   can  modify  data any time by clicking 'Edit' link. To create new user
   use left panel and click 'New user'.
     _________________________________________________________________

3.2.3. New user

   In  order  to create new user, you need to provide at least login name
   and  non  empty  password. Name and email fields are optional. Allowed
   hosts  is  a  coma  separated  list of host or network IP addresses in
   'allow_from'  configuration option style. If that list is empty, hosts
   checking is skipped. Below you can mark specific system access rights.
   If  you  leave  all  those  fields  unchecked  (default), user will be
   granted with 'full access'.
     _________________________________________________________________

3.2.4. Backups

   You  can  manage  your  database  backup copies here. Database copy is
   plain  text  file with SQL statements needed to reconstruct all tables
   and  it's  data,  which  is saved in directory defined with backup_dir
   variable in [directories] section of lms.ini.

   Note

        By default your backups will be placed in lms/backups directory, which
        could be accessed with your browser, without any authentication, so
        it's wise to move it above your Web Server DocumentRoot.

   All  copies  can  be viewed, removed or downloaded to your computer at
   any  time. By clicking on 'recover' icon your current database will be
   deleted  and  replaced  by  the  one  in backup copy. For your safety,
   before   such   operation   current   database   backup  is  performed
   automatically.
     _________________________________________________________________

3.3. Customers

   This  is your customers control center, where you can store and manage
   their  data, their finances and also their computers. You can even cut
   all customer computers off with single mouse click.
   Note

        Automatic cutoff of computers which owners are in debt is performed by
        lms-cutoff Perl script.
     _________________________________________________________________

3.3.1. List

   After  you  select  'List'  you'll see list of your users, that can be
   filtered  based  on  selected  criteria  (customer  status,  group  or
   network)  or  sort  by any highlighted column. Warning triangle on the
   right  side  of  the  record  shows if any warnings are active for the
   customer.  Computer  icon next to triangle informs you about computers
   status  (connected  of  cutoff).  Clicking of any of those two symbols
   toggles status for all computers of the given customer.

   Records  of  customers  with negative balance will have 'payback' icon
   (stack  of coins), which allows you to account instant payment for the
   customer, which value will reset his debt.

   When you click on selected customer you'll get screen with details for
   the  customer,  divided  in several panels: customer details, computer
   details,  liabilities  details  and  customer account details. You can
   also  select to edit any of the panels on this screen, define customer
   liabilities, payoff or charge the customer.
     _________________________________________________________________

3.3.2. New Customer

   This  option  will let you enter data for new customer record. You can
   enter  his last and first name here, or if your customer is also legal
   company,  enter  company  name in "Name" and company representative in
   "Forename"  field.  You should also fill customers phone (up to 3) and
   address  (you can enter additional address for correspondence) and his
   status (connected, waiting in queue, prospect).
   Note

        Wrong capitalization (uppercase) of customer's last name is one of
        most frequent bug reports. Uppercase is implemented via SQL functions
        and thus you should seek for solution in your DB engine configuration.
     _________________________________________________________________

3.3.3. Search

   You're  able  to search customers (including deleted customers), using
   various  criteria. This module is more powerful than appropriate quick
   search  box  in  left  panel,  as you can specify exact field names to
   search  and  if  many customers are found, the list of records will be
   returned, not only the first one.
     _________________________________________________________________

3.3.4. Groups

   This  is  a  place  where  it's possible to divide your customers into
   groups. After you click 'Groups' you'll see list of all defined groups
   with  some basic information. Clicking on selected group will give you
   details  view,  where  you are able to edit this group properties, and
   view/add/remove group members.
     _________________________________________________________________

3.3.5. New Group

   You  can  define  new group here, providing its name is unique, and it
   only  contains  letters, digits and underscore and minus signs. Groups
   are  being  used  in  scripts configuration, and for this reason group
   names cannot contain spaces.
     _________________________________________________________________

3.3.6. Messages

   In this module, you're able to write administrative message which will
   appear  on customers Web browser screen and assign it massively to all
   or  majority  of your customers (just pick them using selection box on
   the left). It's also possible here to deselect administrative messages
   massively here.
     _________________________________________________________________

3.3.7. Printing

   Set of modules to provide printer-friendly version of your records:
     * Customer list with filter and sort abilities,
     * Liability report for any range of customer(s), for specified date,
     * Customer balance for selected period
     _________________________________________________________________

3.4. Nodes

   This  panel  is designed to manage your computer records, namely: view
   computer  list  (with  sorting),  search,  add  new or delete existing
   computers from database and editing capabilities.
     _________________________________________________________________

3.4.1. List

   List  of  computers  will appear after you select 'List' link. You can
   sort  it  by clicking on any highlighted column name. You have several
   icons  on  each computer record: light bulb for connecting and cutting
   off  selected  computer,  warning  triangle for warning screen toggle,
   eraser  for computer removal, pencil for editing details and file icon
   for  viewing  it.  The last module (computer/owner view) might be also
   accessed simply by clicking on selected record.
     _________________________________________________________________

3.4.2. New Node

   You  can  add new computer here. First select good name for it (it may
   contain  letters,  digits, underscore or minus sign), then it's owner.
   IP  and  MAC addresses may be entered manually, or - by clicking arrow
   signs  on the right - you may select them from pool which is read from
   database  and ARP daemon. After you finish - click 'Save'. If you need
   to  enter  more  computers it's helpful to activate 'Display this form
   again' checkbox.
   Note

        To search computer addresses in your network you can use nbtscan
        program. If it's available in system, you can click 'Scan' to get all
        data about computers that are online.
   Note

        You need to create customer and network first, so you can assign new
        computer to it.
     _________________________________________________________________

3.4.3. Search

   You can search for computers here by any given criteria. You can enter
   whole  IP,  MAC or computer name, or just its fragment and search will
   guess for you.
     _________________________________________________________________

3.4.4. Messages

   You  can  write  administration  message  here  and  it will appear on
   customer's  Web browser screen. In this module you can select majority
   or all computers and assign them common message. Just choose computers
   using selectbox on the left (computers with message already on will be
   displayed  in  red). If you only want to assign a message to customer,
   but  don't  want  to turn it on, just write a message and don't select
   any of 'Enable/Disable message' boxes.
     _________________________________________________________________

3.4.5. Printing

   You  can  get  printer  friendly  list  of  your  computers here. It's
   possible to use same filter and sorting capabilities as on 'List'.
     _________________________________________________________________

3.5. Net Devices

   In  this  panel  you're  able  to  keep all your network inventory and
   define  connections  between  your  equipment and customer nodes. Each
   device  (switch,  hub,  router, server) might have also IP address(es)
   assigned.
     _________________________________________________________________

3.5.1. List

   List of devices might include its names, symbols, physical and logical
   location,  description  and  number of available connection ports. You
   might sort its output by any highlighted column. To see device details
   or  define  all  options  and  manage  connected devices just click on
   selected  record.  It's  also  possible to interchange two connections
   between devices on this screen.
     _________________________________________________________________

3.5.2. New device

   Network   device   should  have  unique  name,  all  other  parameters
   (manufacturer,  model, serial number, ports, location and description)
   are optional.
     _________________________________________________________________

3.5.3. Map

   Selection  of  'Map' option draws graphical map of entire network. You
   can  define  root  device, which will appear on top of the map and all
   other devices will be drawn relative to it.
   Note

        You need GD or Ming library compiled in PHP to be able to use
        graphical map.
   Use  'map_type'  option  in section [phpui] section to specify type of
   map.  Set it to "flash" if you've got Ming library or "gd" for graphic
   images.  By  default  (option  not set) LMS will try to generate flash
   map, and when this fails, t will fallback to GD.

   Device  status  is  shown on the map - computers in black are offline.
   Question  mark on device icon means that its status is unknown (device
   has not been scanned yet). To use this functionality you need to setup
   scanning  script  in crontab. Computer is marked as online if computer
   was  online  on  last  successful  scan  and period since last scan is
   lesser  than  defined  in  configuration  (Default: 600 seconds). This
   parameter  can  be  set  with  lastonline_limit  in [phpui] section of
   configuration  file.  Above  feature  applies  both  to  computers and
   devices,  but  in  case  of devices all its ports (IPs) must be up for
   device  to  appear online. Computers status is also available on nodes
   list in 'Nodes' panel.
   Note

        You can use lms-fping Perl script or lmsd daemon to probe hosts
        availability.
     _________________________________________________________________

3.6. IP Networks

   You  can  define  all  your networks here. Network is IP address class
   with  parameters such as domain, DNSes, default gateway and DHCP pool.
   If you use LMS to manage numerous networks or you use numerous address
   classes, it's possible to define them here.
     _________________________________________________________________

3.6.1. List

   Among basic data about network, each record contains information about
   address  space conservation - you can see summary of assigned and free
   addresses. You're able to modify network properties after you click on
   selected network or by clicking 'Edit' icon.

   During  edit  you  are  able to browse list of nodes connected to this
   network,  node name will appear instead of IP number if that number is
   occupied.  If  you  click  on  free  IP  address, without any computer
   assigned  to  it,  new computer form will appear. There are also other
   features  available  for your convenience: Put in order will readdress
   computers  so that there's no gap in the list and Reassign the network
   to move all nodes from one network to another.
     _________________________________________________________________

3.6.2. New Network

   Defines  a  new network. Network needs to have unique name and address
   class,  defined  by  its  IP  address  and  netmask. All other data is
   optional.
     _________________________________________________________________

3.7. Finances

   This  is  actually  the  whole  collection  of modules, that gives you
   possibility  to  efficiently  manage finances of your network. You can
   define  periodical liabilities here (subscriptions), solid liabilities
   (orders),  perform  accounting  operations, check each account history
   and draw invoices and balance sheets.
     _________________________________________________________________

3.7.1. Tariffs List

   When  you  enter  'Tariffs  List'  panel you'll be able to see list of
   liabilities  (Tariffs)  that might be assigned to your customers, with
   basic  informations  about  it. When you select and click on liability
   you'll  move  to  'Tariff'  module  where  you're  able  to  edit  its
   parameters  and  exchange  customers between available liabilities. In
   'Number  of  customers' field you can read number of customers who are
   assigned  to  it  and  two  numbers  in  parenthesis:  total number of
   assignments  and  number  of  active  assignments,  considered  by its
   activity periods.
     _________________________________________________________________

3.7.2. New Tariff

   When defining new tariff you need to enter unique name, amount and tax
   rate.
     _________________________________________________________________

3.7.3. Payments list

   This  is a list of your company payments. Among standard fields you'll
   find  'Account  this  payment'  icon, where you're able to charge your
   account.  Periodical  charges  might  be done with 'lms-payments' Perl
   script,  or  appropriate  module  of  lmsd daemon. Select and click on
   chosen  payment  to  view  'Payment Info' module, where you're able to
   edit its parameters or account given payment to financial database.
     _________________________________________________________________

3.7.4. New payment

   You  have  to  assign  unique  name,  amount and pay date for each new
   payment you setup.
     _________________________________________________________________

3.7.5. Balance sheet

   This  is  history  of  your  financial  operations with total incomes,
   expenditures,  payments and customers liabilities. Printer icon allows
   you to print invoice for corresponding record.
     _________________________________________________________________

3.7.6. New Balance

   You can add new financial operation with this module. It's possible to
   account the same operation for multiple customers at the same time.

   Note

        It's best to use lms-payments Perl script or lmsd daemon to automate
        periodical operations, such as subscription fees. Those modules are
        also able to write out appropriate invoices.
     _________________________________________________________________

3.7.7. Invoices list

   List  of  invoices  that  has been already written out. You're able to
   print  (by  selecting  'Print'  icon)  and check as accounted selected
   invoices.
     _________________________________________________________________

3.7.8. New Invoice

   Allows you to issue an invoice for selected customer manually.
     _________________________________________________________________

3.7.9. Cash Receipts List

   Cash  receipt  it's a proof of customer payment in cash. Receipts list
   can be sorted in any order and filtered like the invoices list. You've
   got also print selected receipts.

   From  list  you  can  go to receipt edition. Making changes in created
   documents  needs  special care, because submitting changes will delete
   old receipt and linked operations and insert new ones.
     _________________________________________________________________

3.7.10. New Receipt

   To  create  new  proof  of  payment  in first place you must to select
   customer  from  list,  set  date  and  number  (better to leave values
   proposed  by  system) Then click 'Submit' to affirm choice. After that
   you  can  add  any  number  of positions with value and description or
   select  them  from list of unpaid customer covenants placed at bottom.
   'Save  and  Print' will finish and save receipt and payments in system
   and display receipt's printout in new window.
     _________________________________________________________________

3.7.11. Import

   If  you  use  homebanking,  and you're able to get a list of financial
   operations  (ie.  from  bank  www or email that they send you), Import
   module  can be used to (semi)automatically load it into LMS accounting
   database and assign to respective customers. You should write (or use,
   if  it's already in distribution) a parser script, which loads data to
   the     cashimport     table.    Please,    check    example    script
   lms-cashimport-ingbs  to see how this is being done. After you run it,
   you  should  get  a  list  of  pending financial operations, in Import
   module,  where  you  can  correct  them and accept into LMS accounting
   database.

   You  can also load previously prepared text file using this module. It
   will  be  read line by line and parsed using setup regular expressions
   to get needed data types (ie. customer id, amount, etc). After file is
   loaded,  you  will  be  presented with the same corrections/acceptance
   screen as above.

   To  setup  regular  expressions,  which  suit  to your input files you
   should  create PHP script which location you must set in import_config
   option  in [phpui] section. Example values and parameters descriptions
   are placed in modules/cashimportcfg.php. Default configuration assumes
   that input data will be in the following format (tab separated):
23.02.2004      Machniak Aleksander     123,45  Internet subscription - 04/2004 ID:0013
15.02.2004      Pain Joseph     123,45  Invoice paid - LMS/34/2004
     _________________________________________________________________

3.7.12. Printing

   There are several options for balance sheet printouts:
     * Balance  sheet for your network including financial operations for
       given period, signed by selected LMS user
     * Total invoiceless income for given period
     * Liability report for given day, for all or selected user
     * Sale Registry, which consists of invoices for given period.
     * Customer balance sheet for given period.
     * Invoices for given period or/and selected customer.
     * Transfer  forms for selected customer or customers group and given
       balance limit (only for polish forms).
     _________________________________________________________________

3.8. Accounts

   It's  now  possible  to  manage accounts from your services using LMS.
   This  functionality  is  provided  for advanced system administrators,
   because  it  requires in-depth knowledge of services running on server
   in order to configure them to use LMS database.

   You  can  create four types of accounts now: shell (1), email (2), www
   (4)  and  ftp (8). Decimal values for internal representation of those
   accounts  are  given  in parenthesis. This approach enables to provide
   multi-type accounts, eg. if you define shell+email+ftp account it will
   be  given  number  11  in database. This means that for recognition of
   account  type  you should use binary sums in WHERE clauses of your SQL
   queries (few examples are written below).

   You have also possibility to define domains and aliases.
     _________________________________________________________________

3.8.1. Accounts

   Account  list contains basic information about your customer accounts.
   It's possible to sort it by any highlighted column title and to filter
   it  for given criteria. You can edit any account clicking 'Edit' icon.
   Administrator (LMS user) is also able to change account passwords.
     _________________________________________________________________

3.8.2. New Account

   To  create new account you have to provide its login, password, choose
   at  least  one  account type and assign customer to it. Domain name is
   optional  and  you'll  need  it  only  if  you  want  to support email
   accounts. Expiration date is also optional, leave it empty to make new
   account valid forever.

   You  can  define any home directory for account. Option homedir_prefix
   from section [phpui] consists default prefix "/home/".
     _________________________________________________________________

3.8.3. Aliases

   Every  account  (email  type  mainly) might have any number of aliases
   that  is needed. Mail server administrator might redirect mail locally
   from  all  those  aliases  to  one  physical  existing  account. Basic
   information  about  alias  and accompanying account is provided on the
   list.  It's  possible to sort this list by any highlighted column name
   and  to  filter  list for given criteria. It's not possible to edit an
   alias  -  if  it's not desirable anymore you have to erase (remove) it
   and create new if needed. Add new aliases at the bottom of the list.
     _________________________________________________________________

3.8.4. Domains

   You're  able to see basic informations about domains on the list. It's
   possible  to  sort  this  list  by  any highlighted column name and to
   filter  list  for given criteria. You can edit domain data by clicking
   'Edit' icon. Add new domain at the bottom of the list.
     _________________________________________________________________

3.8.5. Examples

   The   following   section   contains   fragments   of  proftpd  daemon
   configuration  (version  1.2.10) relevant to process of authentication
   with  using  data  available  in  LMS  database. This example contains
   Postgres  configuration  and optional MySQL configuration in comments,
   followed by pound (hash) sign.

   Example 3-1. Accounts. Proftpd configuration.
  ServerName    "LMS FTP Server"

  #dbname@host:port dbuser dbpass
  SQLConnectInfo lms@localhost:5432 lms mypassword

  SQLAuthTypes Crypt Plaintext
  SQLUserInfo passwd login password uid NULL home NULL
  RequireValidShell off
  SQLAuthenticate users

  # create user home directory if it doesn't exists yet
  SQLHomedirOnDemand on

  # login message
  SQLShowInfo PASS "230" "Last login: %{getlastlogin}"
  SQLLog PASS setlastlogin

  # SQLNamedQuery getlastlogin SELECT "CASE lastlogin WHEN 0 THEN '' ELSE FROM_UNIXTIME(lastlogin) END FROM passwd WHERE login='%u'"
  # SQLNamedQuery setlastlogin UPDATE "lastlogin=UNIX_TIMESTAMP() WHERE login='%u'" passwd
  SQLNamedQuery getlastlogin SELECT "CASE lastlogin WHEN 0 THEN '' ELSE lastlogin::abstime::timestamp::text END FROM passwd WHERE login='%u'"
  SQLNamedQuery setlastlogin UPDATE "lastlogin=EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)) WHERE login='%u'" passwd

  # We limit access to valid (not expired) accounts with ftp type
  # SQLUserWhereClause "type & 8 = 8 AND (expdate = 0 OR expdate > UNIX_TIMESTAMP())"
  SQLUserWhereClause "type & 8 = 8 AND (expdate = 0 OR expdate > EXTRACT(EPOCHFROM CURRENT_TIMESTAMP(0)))"

   Next  example  will show us how to configure Postfix 2.1.1 mail server
   with  Cyrus-SASL  2.1.19 and Courier-IMAP/POP3 3.0.4, so that they use
   LMS database. LMS accounts will be virtual, which means that they will
   be  all  maintained  by  one uid on server with mail stored in Maildir
   format.

   You'll  need  to  patch your SASL for encrypted passwords, because LMS
   database contains them only in this form. In comments we have provided
   MySQL  specific options. Only fragments relevant to database setup are
   shown below:

   Example      3-2.      Accounts.     Mail     server     configuration
   (postfix+sasl+courier).
# smtpd.conf file (Cyrus-SASL):

pwcheck_method: auxprop
#sql_engine: mysql
sql_engine: pgsql
sql_user: lms
sql_passwd: dbpass
sql_hostnames: localhost
sql_database: lms
#sql_select: SELECT password FROM passwd, domains WHERE domainid = domains.id
#       AND login='%u' AND domains.name ='%r' AND type & 2 = 2
#       AND (expdate = 0 OR expdate > UNIX_TIMESTAMP())
sql_select: SELECT password FROM passwd, domains WHERE domainid = domains.id
        AND login='%u' AND domains.name ='%r' AND type & 2 = 2
        AND (expdate = 0 OR expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)))
password_format: crypt
mech_list: login plain

# authpgsqlrc (or authmysqlrc) (Courier):

# user postfix (owner of mail directory)
#MYSQL_UID_FIELD '1004'
PGSQL_UID_FIELD '1004'
# group postfix (owner of mail directory)
#MYSQL_GID_FIELD '1004'
PGSQL_GID_FIELD '1004'
#MYSQL_PORT             3306
PGSQL_PORT              5432
#MYSQL_USERNAME         lms
PGSQL_USERNAME          lms
#MYSQL_PASSWORD         dbpass
PGSQL_PASSWORD          dbpass
#MYSQL_DATABASE         lms
PGSQL_DATABASE          lms
#MYSQL_SELECT_CLAUSE SELECT login, \
#       password, '', 104, 104, '/var/spool/mail/virtual', \
#       CONCAT(login,'/'), '', login, '' \
#       FROM passwd, domains WHERE domainid = domains.id \
#       AND login = '$(local_part)' AND domains.name = '$(domain)' \
#       AND type & 2 = 2 AND (expdate = 0 OR expdate > UNIX_TIMESTAMP())
PGSQL_SELECT_CLAUSE SELECT login, \
        password, '', 104, 104, '/var/spool/mail/virtual', \
        login ||'/', '', login, '' \
        FROM passwd, domains WHERE domainid = domains.id
        AND login = '$(local_part)' AND domains.name = '$(domain)' \
        AND type & 2 = 2 \
        AND (expdate = 0 OR expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)))

# main.cf (Postfix):

virtual_mailbox_base = /var/spool/mail/virtual
virtual_mailbox_domains = pgsql:/etc/postfix/pgsql_virtual_domains_maps.cf
virtual_mailbox_maps = pgsql:/etc/postfix/pgsql_virtual_mailbox_maps.cf
virtual_alias_maps = pgsql:/etc/postfix/pgsql_virtual_alias_maps.cf

# pgsql_virtual_domains_maps.cf (Postfix):

user = lms
password = dbpass
hosts = localhost
dbname = lms
#MySQL plugin doesn't support query option, thus we build query differently
#select_field = name
#table = domains
#where_field = name
query = SELECT name FROM domains WHERE name = '%s'

# pgsql_virtual_mailbox_maps.cf (Postfix):

user = lms
password = dbpass
hosts = localhost
dbname = lms
#table = passwd, domains
#select_field = CONCAT(login,'/')
#where_field = CONCAT(login,'@',domains.name)
additional_conditions = AND domainid = domains.id
#       AND type & 2 = 2 AND (expdate = 0 OR expdate > UNIX_TIMESTAMP())
query = SELECT login || '/' FROM passwd, domains WHERE domainid = domains.id
        AND login = '%u' AND domains.name = '%d'
        AND type & 2 = 2
        AND (expdate = 0 OR expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)))

# pgsql_virtual_alias_maps.cf (Postfix):

user = lms
password = dbpass
hosts = localhost
dbname = lms
#table = passwd, domains, aliases
#select_field = CONCAT(passwd.login,'@',domains.name)
#where_field = CONCAT(aliases.login,'@',domains.name)
#additional_conditions = AND  passwd.domainid = domains.id AND passwd.id = aliases.accountid
query = SELECT passwd.login || '@' || domains.name FROM passwd, domains, aliases
        WHERE passwd.domainid = domains.id AND passwd.id = aliases.accountid
        AND aliases.login = '%u' AND domains.name = '%d'
     _________________________________________________________________

3.9. Mailing

   Mailing  is  component  where you can spam groups of your customers if
   you  have  to  communicate  something  to  them. Obviously you need to
   specify  sender  name  and address, write your message in text box and
   select appropriate group of recipients. Your attendance can be grouped
   by  status,  network  or  customer  groups.  If you use mail server on
   remote  host,  you  will  need  to  set  options smtp_host, smtp_port,
   smtp_username, smtp_password in [phpui] section.

   In  message  body  you  can  use  variables, which will be replaced by
   customer data:
   %customer - name/lastname and forename
   %balance - balance value (with sign)
   %cid - customer ID
   %pin - customer PIN
   %last_10_in_a_table - last 10 operations on customer account

   Note

        Your server has to support PEAR::Mail for this to work.
   Note

        It's best to use lms-notify Perl script or notify module of lmsd
        daemon to send emails automatically whenever customer is in debt.
     _________________________________________________________________

3.10. Reload

   Click on 'Reload' and reload request or command should execute. If you
   did  configure  hosts,  you  will  see  list of hosts for selection to
   reload  configuration on selected hosts. What services and how they're
   updated  is  configured  in LMS-MGC or lmsd daemon. You'll find needed
   information  about  configuration  in  appropriate  chapters  of  this
   documentation.
     _________________________________________________________________

3.11. Stats

   This  is  interface  to view bandwidth consumption per host statistics
   enclosed  in  bar  graphs.  Statistics  contains  data  about sent and
   received bytes for given interface for each node. Using drop down menu
   you can quickly generate statistics for given time periods: last hour,
   day, 30 days or year.
   Note

        You need working lms-traffic Perl script or lmsd daemon running to
        collect statistics.
     _________________________________________________________________

3.11.1. Filter

   Before you can see graphs you can define parameters to limit period or
   network  (if  you  have  many), top number of computers considered and
   sort output as you like (ie. by top download).
     _________________________________________________________________

3.11.2. Compacting

   Depending  on chosen update frequency amount of database data used for
   statistics  might  grow  fast,  which  will  lead to extension of time
   needed  to  generate  statistics. For that reason in 'Compacting' menu
   you're  able  to  shrink  your  database  size without data loss. This
   module will compact data using following logic:
     * Low   precision:  data  from  previous  date  and  older  will  be
       approximated  to  one  day.  If you save data each 10 minutes 6*24
       records will be compacted to one.
     * Medium  precision:  data  older than month will be approximated to
       one day.
     * High  precision: data older than month will be approximated to one
       hour.

   Warning

           Data approximation is irreversible.
     _________________________________________________________________

3.11.3. Printing

   Here  you  can  print  statistics of given customer in selected month.
   Printout  consist  upload/download  summary grouped by month days with
   average transfer speed.
     _________________________________________________________________

3.12. Helpdesk

   Helpdesk  (or  Request Tracker) is customer request management system.
   It's possible to keep history of all requests and questions here, both
   reported  by  customers  and  users  not  registered  in LMS database.
   Reports  can  be  grouped  in  queues  (categories) and you're able to
   search  them  for  a  given  criteria.  It's possible to define access
   rights for LMS users to each queue.

   You  have  quick search box in left (menu) panel, which may be used to
   jump  to  appropriate  ticket  giving  ticket  id  or  reporter  name.
   Searching  by  reporter name will give a list of all tickets available
   for this user.

   Each  ticket includes history built on messages sent by administrators
   (LMS  users)  and  customers.  Administrator  may  send his message to
   customer  specifying  recipient name and clicking 'Submit/Send', email
   will  be  sent  with queue address as sender, or - if it's empty - LMS
   user  address.  All  messages,  including  those sent, are recorder in
   ticket  history. Each ticket may be in one of the states: new, opened,
   resolved or dead.

   Please look at lms-rtparser script which has been developed to support
   incoming requests and outgoing comments by your mail server.
     _________________________________________________________________

3.12.1. Queues List

   Basic  informations  and  request  statistics  are available on queues
   list.  Select  and  click  on  chosen  queue  to  display  all tickets
   belonging  to  it.  You  can  also  go  to  detailed  view  (including
   permissions)  about  queue  or remove given queue. Removing queue will
   also remove all belonging tickets from database.
     _________________________________________________________________

3.12.2. New queue

   Queue  (category)  contains  a name, optional description and optional
   email address, used in correspondence. 'Permissions' table defines LMS
   users   access   to   this   queue,   which  overrides  those  set  in
   'Administration',  which  means,  that  the user who has 'full access'
   permissions  won't be able to see queue and tickets placed in it until
   he's  given  access  to  that  queue.  Enabling  'write'  (tickets and
   comments  edit ability) to user automatically gives him 'read' access.
   'Notices'  privilege  is  used  to  notify users about new tickets. If
   'newticket_notify'  option  is  enabled  all users with this privilege
   will get notifications by email.
     _________________________________________________________________

3.12.3. Searching

   Tickets  are  searchable  by  all given criteria (AND not OR). You can
   provide  subject,  owner,  queue, status and reporter for your search.
   Customers  may be selected from drop-down list, unregistered users may
   be searched by name or email address.
     _________________________________________________________________

3.12.4. New ticket

   For  each  new  ticket you need to provide subject, content, queue and
   reporter.  Unregistered  users  (not  in customers database) should be
   recorded  using  'Submitter' fields. You can provide email address (in
   both  registered/unregistered  cases)  if  ticket  will be running via
   email.
     _________________________________________________________________

3.13. Timetable

   Timetable  is  your  time scheduler, where each user may setup his own
   calendar. Events or tasks being put here may be also visible for other
   users  and  consist  a  list of assigned clients, which make this tool
   usable for service crew management.

   There  is  an  additional  lms-reminder  script, which may be executed
   periodically to remind users about their pending tasks.
     _________________________________________________________________

3.13.1. Timetable (Task list)

   Main  timetable shows list of days starting from day which is selected
   from   calendar   popup.   A  number  of  days  displayed  depends  on
   timetable_days_forward  configuration  option  and defaults to 7 days.
   From task list you might print a day plan or go to event edit screen.
     _________________________________________________________________

3.13.2. New event

   You  can  add  new  task to the Timetable by selecting short title and
   start  date and time (or time span). All other fields are optional. By
   selecting  'private'  option you can hide current event from the other
   users, so that it will be visible only for event creator. This feature
   allows you to run your own, private calendar.
     _________________________________________________________________

3.13.3. Search

   You  can  search  in  Timetable  by  the following criteria: time span
   (start  and  end date), client affected, client or fragment of text in
   title,  event  description  or its notes. List of results will include
   events that match all entered criteria.
     _________________________________________________________________

3.14. Configuration

3.14.1. User Interface

3.14.1.1. Basics

   Since  LMS  1.5.3  you're  able  to  configure  all UI-related options
   directly  via  LMS-UI,  instead  of editing lms.ini. Those options are
   stored  in database and you first need to import them from your config
   file  (even if you haven't edited anything yet, default values will be
   imported). This can be done by clicking on the link presented on empty
   list.

   Note

        Options setup with LMS-UI have higher priority than those in
        configuration file. With options setup in UI, the configuration will
        be still imported from file but values will be then overwritten by
        those found in DB.

   Note

        Daemon read some options other than its configuration from database
        only, so it's preferred to store configuration in database.

   In  order  to manually add new option click 'Add option' on the bottom
   of  the  list.  To  edit  option value, click on its record. You'll be
   given  with  edit form, where you are also able to remove this option.
   Changing  option  status  allows  you to turn it on and off instantly.
   When an option is off, default value will be used (if it posses any).
     _________________________________________________________________

3.14.1.2. Configuration Options List

   Here  we've  got  the  list of UI configuration options. Those options
   should  be placed in [phpui] section. The rest of options is described
   in appropriate chapters.
     * allow_from (optional)
       List  of  networks  or  IP addresses, which have access to LMS. If
       empty,  every  IP address is permitted. You can write here list of
       addresses  or  address classes and LMS will dismiss every unwanted
       user with HTTP 403 error.
       Example:    allow_from    =   192.168.0.0/16,   213.25.209.224/27,
       213.241.77.29
     * lang
       User  interface  language code (ISO). IF not set, language will be
       based on HTML browser settings. Default: en
       Example: lang = pl
     * timeout
       Timeout  for WWW session. User will be log out if he won't perform
       any action in such number of seconds. Default: 600
       Example: timeout = 900

 Warning

         It's not possible to not to have any timeout. If you set this value to
         zero, you won't be able to use LMS at all!
     * customerlist_pagelimit
       Limit  of  records  that can be displayed on one page of customers
       list. Default: 100
       Example: customerlist_pagelimit = 10
     * nodelist_pagelimit
       Limit  of records that can be displayed on one page of nodes list.
       Default: 100
       Example: nodelist_pagelimit = 10
     * balancelist_pagelimit
       Limit  of  records  that  can be displayed on one page of customer
       balance. Default: 100.
       Example: balancelist_pagelimit = 50
     * invoicelist_pagelimit
       Limit  of  records  that  can be displayed on one page of invoices
       list. Default: 100
       Example: invoicelist_pagelimit = 50
     * ticketlist_pagelimit
       Limit  of  records  that  can  be  displayed on one page of ticket
       (requests) list. Default: 100
       Example: ticketlist_pagelimit = 50
     * networkhosts_pagelimit
       Limit  of  records that can be displayed on one page of nodes with
       network information. Default: 256
       Example: networkhosts_pagelimit = 1024
     * accountlist_pagelimit
       Limit  of  records  that  can be displayed on one page of customer
       accounts. Default: 100
       Example: accountlist_pagelimit = 50
     * domainlist_pagelimit
       Limit  of  records  that  can  be  displayed on one page of system
       domains. Default: 100
       Example: domainlist_pagelimit = 50
     * aliaslist_pagelimit
       Limit  of  records  that  can  be  displayed  on  one page of user
       aliases. Default: 100
       Example: aliaslist_pagelimit = 50
     * configlist_pagelimit
       Limit  of  records  that  can  be  displayed  on  one  page  of UI
       configuration list. Default: 100
       Example: configlist_pagelimit = 50
     * taxratelist_pagelimit
       Limit  of  records  that can be displayed on one page of tax rates
       list. Default: 100
       Example: taxratelist_pagelimit = 50
     * numberplanlist_pagelimit
       Limit  of  records  that can be displayed on one page of numbering
       plans list. Default: 100
       Example: numberplanlist_pagelimit = 50
     * documentlist_pagelimit
       Limit  of  records  that can be displayed on one page of documents
       list. Default: 100
       Example: documentlist_pagelimit = 50
     * reload_type
       Reload type. Allowed values:
       exec  -  execute  some  command  (usually  with  sudo,  script  or
       something else, configurable below)
       sql - doing SQL writes (can be also set to custom query)
       Default: sql.
       Example: reload_type = exec
     * reload_execcmd
       Command  to run during reload, if reload_type is set to 'exec'. By
       default  /bin/true.  This  string  is send to system() command, so
       make  sure that you know what you're doing. :) Besides, semicolons
       should  be  parsed by bash, but LMS splits that string and execute
       commands  separately.  In  commands  you can use '%host' variable,
       which is replaced by defined host name (Configuration -> Hosts).
       Example: reload_execcmd = "sudo /usr/bin/reload_lms.sh %host"
     * reload_sqlquery
       SQL query executed while reload, if reload_type = sql. By default,
       query  sets  reload  order  for  daemon lmsd. You can use '%TIME%'
       template in your query which will be substituted with current UNIX
       timestamp and '%host' for host name. WARNING! Semicolon is handled
       as  query  separator, which means that you can enter couple of SQL
       queries separated by semicolon sign.
       Example:    reload_sqlquery   =   "INSERT   INTO   reload   VALUES
       ('1','%TIME%')"
     * force_ssl
       Enforce  SSL  for  all  connections. Setting this option to 1 will
       turn  LMS  into  enforcing SSL connections by applying redirect to
       'https://'.$_SERVER[HTTP_HOST].$_SERVER[REQUEST_URI]    at   every
       access without SSL. Default: 0 (off).
       Example: force_ssl = 1
     * allow_mac_sharing
       Allows  for  node  addition  even if its MAC address is not unique
       (not  checking  that  some computer have that MAC yet). Default: 0
       (off)
       Example: allow_mac_sharing = 1
     * smarty_debug
       Enable  Smarty  debug  console.  Useful for tracking values passed
       from PHP to Smarty. Default: 0 (off).
       Example: smarty_debug = 1
     * lang_debug
       Enable   LMS   language   console.  Useful  for  tracking  missing
       translation strings. Default: 0 (off).
       Example: lang_debug = 1
     * debug_email
       E-mail address for debugging - messages sent from module 'Mailing'
       will  be delivered to this address instead of sending them to real
       users.
       Example: debug_email = root@localhost
     * default_zip, default_city, default_address
       Default  zip code, city and street used on "new user" form. Useful
       when we have many users on the same street.
       Example: default_zip = 39-300
     * use_current_payday
       Forces  to  use  current  day of month as a payment day instead of
       most often used day. Default: 0 (off).
       Example: use_current_payday = 1
     * lastonline_limit
       Specify  time  (in  seconds),  after  which  node  will  be marked
       offline.  It  should  match  frequency  of  execution  for  script
       responsible for checking nodes activity (i.e. lms-fping). Default:
       600.
       Example: lastonline_limit = 300
     * timetable_days_forward
       Specify   number  of  days  (including  current  day)  visible  on
       timetable. Default: 7.
       Example: timetable_days_forward = 2
     * arpd_servers
       List  of  arpd  servers  for  reading  MAC  addresses  from remote
       networks.  That list should include IP[:port] items separated with
       spaces. Default: empty.
       Example: arpd_servers = 192.168.1.1 192.168.2.1
     * helpdesk_backend_mode
       When  enabled,  all messages in helpdesk system (except those sent
       to ticket reporter) will be sent to mail server to the appropriate
       queue  address.  Mail server should run lms-rtparser script, which
       will write messages to database. Default: disabled.
       Example: helpdesk_backend_mode = On
     * helpdesk_sender_name
       Name  of  message  sender or predefined values: 'queue' - ticket's
       queue name, 'user' - name of logged user (sender). Default: empty.
       Example: helpdesk_sender_name = Helpdesk
     * newticket_notify
       If   enabled,   after   new   ticket  addition  system  will  send
       notification  emails  to  all  users  with  rights  to  the queue.
       Default: disabled.
       Example: newticket_notify = On
     * to_words_short_format
       Specify format of verbal amounts representation (on invoices). For
       value  "1"  verbal  expand of 123,15 will be "one two thr 15/100".
       Default: 0.
       Example: to_words_short_format = 1
     * nodepassword_length
       Length of (auto-generated) node password. Max.32. Default: 16.
       Example: nodepassword_length = 8
     * smtp_host, smtp_port, smtp_username, smtp_password
       Parameters   for   smtp   authorization   in   mailing.   Default:
       127.0.0.1:25.
       Example: smtp_host = mail.domain.pl
     * smtp_auth_type
       Smtp  authorization  method  in  mailing.  By default LMS (exactly
       PEAR::Net_SMTP) will use the best supported method. Default: none.
       Example: smtp_auth_type = DIGEST-MD5
     * gd_translate_to
       Charset  of  data  that  GD  library  expects  (useful  if GD need
       ISO-8859-2 instead of UTF-8 to feed imagetext() function. Default:
       ISO-8859-2.
       Example: gd_translate_to =
     * check_for_updates_period
       How often to check for LMS updates (in seconds). Default: 86400.
       Example: check_for_updates_period = 604800
     * default_taxrate
       Specify  value  (not  label) of tax rate which will be selected on
       drop-down lists by default. Default: 22.
       Example: default_taxrate = 22.0
     _________________________________________________________________

3.14.2. Tax Rates

   Before you have to begin with financial system you will need to define
   tax  rates  which  you will use. On the list are place all rates data.
   It's  possible  to  edit tax rate, but system will not allow to change
   value of rate that was used in the past. Also isn't possible to delete
   that rate.

   Link  'Add tax rate' moves you to the form, where you can define a new
   rate.  Tax  rate  label  is  displayed  on  select  lists  and invoice
   printout. Value of tax rate is a number from 0 to 100 with two decimal
   places  precision. Taxing status is used for tax-free rate, that means
   the rest of defined tax rates should have taxing enabled.

   Tax  rate  which  will  be  selected by default on lists is defined by
   default_taxrate option in section [phpui].
     _________________________________________________________________

3.14.3. Number plans

   This  feature  allows  you  to  add  unique  numbering plan (numbering
   sequence)  for  each  type  of  documents  created  in  LMS. It's also
   possible  to  define different sequences within one type of documents.
   For  each  document type you might define default sequence (important,
   ie.  when  you're  issuing  invoices automatically, as perl scripts or
   daemon will use this default scheme when creating new document).

   For  each sequence you should also define time span, that is period in
   which  sequence  numbers  will be unique. When time span selected will
   reach  its end, sequence will be zeroed. You are able to set period to
   one  of:  daily,  weekly  (Monday  to  Sunday),  monthly, quarterly or
   annually.

   Numbering  plans  list  consist  of  all  its  identifying information
   included,  followed  by  example number generated using this plan plus
   number  of  documents  created  with  this plan. You might select 'Add
   plan' to enter new sequence. Editing is possible by clicking the field
   that  you  want  to  change. Deletion of plan is only possible when no
   documents has been created with that yet.

   Sequence  template  might be any string, which consist some of symbols
   (specifiers)  known  from  PHP strftime function. Detailed information
   and  list of all symbols can be find in PHP Manual. The most important
   and  the only required symbol in sequence template is '%N', which will
   be  substituted  with  incremented  document number. All other symbols
   will  expand  to  document's  date  of  issue. Below you can find most
   popular ones:
     * %N - integer number, uniquely identifying document
     * %[1-9]N - as above, but with leading zeroes, ie. '%4N' will return
       '0012' for 12
     * %Y - year as a 4 digit number
     * %y - year as a 2 digit number
     * %m - month number with leading zero (01 to 12)
     * %b - short month name (according to system locales)

   Note

        If you have no numbering plans defined, each document will take
        default number as of '%N/LMS/%Y' with annual time span.
     _________________________________________________________________

3.14.4. Hosts

   This  section  defines host names of those machines (routers, servers)
   that  read  its  configuration  from LMS database and where scripts or
   lmsd daemon will be setup.

   Each  host  name should be unique and it's recommended to be machine's
   real name, which could be obtained by running hostname command on each
   of them (assuming they're all u*ix hosts).
     _________________________________________________________________

3.14.5. Daemon

   When you create hosts list, you will be able to configure daemon lmsd.
   Daemon configuration is described in appropriate chapter.
     _________________________________________________________________

Chapter 4. Scripts

4.1. Installation

   Configuration  of  each  Perl script should be enclosed in appropriate
   section  of  lms.ini  file.  Scripts  should  be  taken  from lms/bin/
   directory and placed in /usr/sbin. After the move, you have to include
   them  in  your  crontab,  so that they will be executed automatically,
   which is probably what you want to do.

   For  example crontab entry which will execute lms-payments script each
   day one minute after midnight should take a form of:
1 0 * * *       /usr/sbin/lms-payments 1 > /dev/null

   You  should  read  man  crontab  to learn how to exactly schedule your
   scripts.

   Most LMS scripts have following command line options:
-C file     location and name of alternative configuration, default: /etc/lms/lms.ini
-q          run script without any output
-h          help (usually list of valid command line options)
-v          information about script version
     _________________________________________________________________

4.2. List of available scripts

   Table 4-1. Executable scripts list
          Name                                Description
       lms-notify              Massive mailing for customer notification
     lms-notify-sms            Notifies customer about his debt with SMS
       lms-cutoff                 Cutoff of customers who are in debt
      lms-etherdesc       MAC address - hostname pair file creation for iptraf
      lms-payments       Accounting subscription fees (periodical) with invoice
                                               writeouts
       lms-traffic                 Bandwidth consumption calculation
 lms-traffic-logiptables             Bandwidth probe with iptables
       lms-makearp                  ARP table (/etc/ethers) creation
    lms-makedhcpconf             DHCP server configuration (dhcpd.conf)
    lms-makeiptables            Configuration of iptables firewall rules
    lms-makeipchains            Configuration of ipchains firewall rules
    lms-makeopenbsdpf         Configuration of OpenBSD packet filter rules
   lms-makeoidentconf                   Configuration of oident
    lms-sendinvoices             Distribution of invoices to customers
      lms-makemacs            Firewalling with use of source MAC addresses
      lms-makehosts                     /etc/hosts file creation
    lms-makewarnings              Redirect rules for customers in debt
    lms-makemessages       Redirect rules for customers in debt with warning
                                                message
        lms-fping                          Online nodes scan
      lms-rtparser                      Helpdesk backend for MUA
     _________________________________________________________________

4.3. Description and configuration

4.3.1. lms-notify

   lms-notify  is  perfect  tool  to  remind your customers that they are
   actually  the  ones who cover all your network and WAN links costs. It
   makes  you  possible  to  create  numerous  text templates for various
   occasions and use them for mailing your customers.
     _________________________________________________________________

4.3.1.1. Templates

   You can use following variables in your templates:
     * %date-m - will be substituted with current month in numerical form
       with leading zero, eg. 02
     * %date-y - will be substituted with current year, eg. 2003
     * %date_month_name  -  will  be substituted with current month name,
       eg. March
     * %saldo  -  will  be substituted with current customer balance, eg.
       535
     * %abonament - will be substituted with customer's subscription fee,
       eg. 107
     * %b - customer balance with opposite sign, eg. 107
     * %B - customer balance with real sign, eg. -107
     * %pin - PIN code of the customer
     * %phone1 - customer's 1st phone number
     * %last_10_in_a_table  -  list  of  last 10 operations on customer's
       account, eg.

   Example 4-1. Lms-notify: example of last 10 customer's operations
-----------+------------------------------------------------------+---------
2003-02-02 | Subscription for month 2003/02                       |  107.00
2003-02-01 | Payment                                              | -107.00
2003-02-01 | Subscription for month 2003/02                       |  107.00
2003-02-01 | Payment                                              | -321.00
2003-01-31 | Subscription for month 2003/01                       |  107.00
2003-01-31 | Subscription for month 2003/01                       |  107.00
2003-01-31 | Subscription for month 2003/01                       |  107.00
-----------+------------------------------------------------------+---------

   Example 4-2. Lms-notify: example of mailing template
NOTE: This message has been generated automatically.

We kindly remind that you have debt on your internet service provide account
for the amount of $ %B.

If you have already regulated your subscription fees for current month, that
is %date-m %date-y, please just skip this message.

If you think this message was sent to you in error, please contact our
customer service representative.

All information about payments could be also found at:
http://bigpro.com/myAccount/

If you want to regulate your account status, please contact our accountant:

Aldfert Rule
phone: 0-509031337
e-mail: alde@staff.bigpro.com

Garmund Cooper
phone: 0-606666666
e-mail: gcooper@free.bigpro.com

PS. Last 10 operations on your account has been attached below for your
convenience.

Date       | Description                                          | Amount
%last_10_in_a_table

--
Big and Professional Internet Provider, BigPro ISP
http://www.bigpro.com/
     _________________________________________________________________

4.3.1.2. Configuration

   Configuration  of  lms-notify  should be set in lms.ini file, [notify]
   section. Following parameters are valid:
     * limit
       Lets  you  setup  limit of customer debt. Email will be sent below
       that value. Default: limit = 0
       Example: limit = -20
     * mailsubject (mandatory)
       Lets  you  setup  subject  of  email  sent.  You can use following
       templates, with meanings identical to those set in email template:
       %B, %b, %date-y, %date-m, %last_10_in_a_table. Default: none.
       Example: mailsubject = Debt information
     * mailtemplate (mandatory)
       Lets you setup mail template which will be sent. Default: none.
       Example: mailtemplate = /etc/lms/notifytemplate.txt
     * mailfrom (mandatory)
       Lets you setup email of the sender. Default: none.
       Example: mailfrom = staff@bigpro.com
     * mailfname (mandatory)
       Sender name. Default: none
       Example: mailfname = Administrators
     * mailcharset
       Message character set (Content-Type). Default: UTF-8
       Example: mailcharset = ISO-8859-2
     * smtp_server
       SMTP server to be used when sending emails. Default: 127.0.0.1
       Example: smtp_server = smtp.bigpro.com
     * debug_email (optional)
       Email  address  for  debugging.  All  email  will  be sent to this
       address instead of sending to real customers. Default: not set.
       Example: debug_email = lexx@domain.pl
     _________________________________________________________________

4.3.2. lms-notify-sms

   lms-notify-sms  is  similar  to  lms-notify, but it's intended to send
   reminders  via  SMS.  You  need  Nokia  cellphone  and gnokii software
   (www.gnokii.org) for this script to work.

   Configuration  of  lms-notify-sms  should  be  set  in  lms.ini  file,
   [notify-sms] section. Following parameters are valid:
     * limit
       Lets you setup limit of customer debt. SMS will be sent below that
       value. Default: 0
       Example: limit = -20
     * smstemplate (mandatory)
       Message template. Default: not set.
       Example: smstemplate = /etc/lms/smstemplate.txt
     _________________________________________________________________

4.3.3. lms-cutoff

   This  script allows to cutoff (actually mark as cutoff in database and
   cutting  off  should  be  performed  by one of firewall rules creation
   script) customers whose debt is below some defined value.

   Configuration  of  lms-cutoff  should be set in lms.ini file, [cutoff]
   section. Following parameters are valid:
     * limit (optional)
       Lets  you setup limit of customer debt. Customer will be marked as
       disconnected below that value. Default: 0
       Example: limit = -20
     * message (optional)
       If  not  empty,  that  message  will be written to warning message
       field  in  customer record after cutting him off. You can use %now
       variable,  and  it  will  be  replaced  by  current date. Default:
       'Automatic  cutoff  caused  by  exceeding  of liabilities limit on
       %now'
       Example: message = ''
     _________________________________________________________________

4.3.4. lms-payments

   This  script  is  being used to calculate and account subscription and
   solid  (fixed)  fees.  It  also  accounts your company liabilities and
   makes  invoices.  You  should  allow it to run daily if you want it to
   make it work done well.

   This scripts may be configured with two options related to invoices in
   [payments] section of lms.ini file:
     * deadline (optional)
       Payment deadline in days. Default: 14
       Example: deadline = 7
     * paytype (optional)
       Type of payment. Default: 'TRANSFER'
       Example: paytype = 'CASH'
     * suspension_description (optional)
       Suspension  description for suspended liabilities added at the end
       of comment. Default: ''
       Example: paytype = '(suspension)'
     * comment (optional)
       Description on invoice attached to every periodical assigment
       Default: '%tariff subscription for period %period'
       Some keywords are substitiuted:
       %tariff - subscription name
       %period  -  period (counted from current day to the last in cycle,
       in YYYY/MM/DD form)
       %current_month  - period form 1st day of current month to the last
       day
       %desc - tariff description
       Example: comment = 'Subscription for %current_month'

   Script  has  also  one useful command line parameter: --fakedate (-f).
   With  this  option  you  can make that script will execute with system
   date    (in    format    YYYY/MM/DD)    other    that   current,   eg.
   --fakedate=2004/10/10.
     _________________________________________________________________

4.3.5. lms-traffic

   This  script is an interface between your application and LMS database
   and  is  intended  to  gather  bandwidth  usage statistics. You should
   provide number of bytes received and sent by each computer, which will
   be stored in LMS DB next to computer id and current timestamp. It's up
   to  you  how often this configuration will be refreshed, just remember
   to  set your application to refresh its data in similar interval. Best
   sources  of  data  are iptables or ipchains. You can also use external
   program, eg. ipfm.

   Browsing  gathered  statistics  with several filtering capabilities is
   available in LMS-UI in main menu, menu 'Statistics'.
     _________________________________________________________________

4.3.5.1. Installation

   Before you can run lms-traffic you need to create data file which will
   be read in. Format of the file should be as follows:
<IP_address> <n_of_spaces> <upload_bytes> <n_of_spaces> <download_bytes>
<IP_address> <n_of_spaces> <upload_bytes> <n_of_spaces> <download_bytes>
...

   Note

        Example script utilizing iptables might be found in
        sample/traffic_ipt.pl file.

   Next you should install lms-traffic script and your custom script into
   crontab.  Among  standard  options  you  can  use define location with
   created data file.
-f=/file        location and name of data file, default: /var/log/traffic.log

 Warning

         Frequency checks should be set not higher than 10 minutes, due that
         each execution will write new database record for each computer. Thus,
         statistics database might grow fast and it might take longer to
         generate desired statistics.
     _________________________________________________________________

4.3.6. lms-traffic-logiptables

   This  script uses iptables to gather received and sent data statistics
   for  each  computer. Data is being read from firewall rules, which are
   created   on-the-fly.  Thus,  you  are  not  responsible  for  setting
   appropriate   rules   or  running  custom  statistics  collector  (eg.
   lms-traffic).

   Configuration  of  lms-traffic-logiptables  should  be  set in lms.ini
   file, [traffic-logiptables] section. Following parameters are valid:
     * outfile
       Location of file with iptables rules. Default: /etc/rc.d/rc.stat
       Example: outfile = /etc/rc.d/rc.stat
     * iptables_binary
       Location of iptables binary. Default: /usr/sbin/iptables
       Example: iptables_binary = /usr/local/sbin/iptables
     * wan_interfaces
       Interface(s)  name(s)  that  should  be  considered.  Default: not
       defined.
       Example: wan_interfaces = eth0
     * local_ports
       List of source/destination ports for packet counting. Default: not
       defined.
       Example: local_ports = 80
     * script_owneruid
       UID of 'outfile' script owner. Default: 0 (root).
       Example: script_owneruid = 0
     * script_ownergid
       GID of 'outfile' script owner. Default: 0 (root).
       Example: script_ownergid = 0
     * script_permission
       Permissions of 'outfile' script. Default: 700 (rwx------).
       Example: script_permission = 700
     _________________________________________________________________

4.3.7. lms-makedhcpconf

   This module creates DHCP configuration script - dhcpd.conf.

   Configuration  of  lms-makedhcpconf  should  be  set  in lms.ini file,
   [dhcp] section. Following parameters are valid:
     * config_file
       Output file location. Default: /etc/dhcpd.conf
       Example: config_file = /tmp/dhcpd.conf
     * networks
       List  of  (space  separated)  networks,  that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = public-custa public-custb
     * customergroups
       List   of  (space  separated)  customer  groups,  that  should  be
       considered   while   creating   configuration   file.   If  unset,
       configuration will include all customer groups.
       Example: customergroups = group1 group2
     * default_lease_time
       Default lease time. Default: 86400.
       Example: default_lease_time = 43200
     * max_lease_time
       Maximal lease time. Default: 86400.
       Example: max_lease_time = 43200
     * ignore_ddns
       Dont  put  'ddns-update-style  none;' on beginning of file. Useful
       for older (2.2) versions of DHCP. Default: Off.
       Example: ignore_ddns = 1
     * log_facility
       Logging  options  for  DHCP  daemon.  Default  is  applied  if not
       specified.
       Example: log_facility = 7
     * script_owneruid
       UID of 'config_file' config owner. Default: 0 (root).
       Example: script_owneruid = 0
     * script_ownergid
       GID of 'config_file' config owner. Default: 0 (root).
       Example: script_ownergid = 0
     * script_permission
       Permissions of 'config_file' file. Default: 600 (rwx------).
       Example: script_permission = 700

   You   can   setup   leases   time   on   per-host  basis  by  creating
   [dhcp:network_name] section (in lowercase), eg.
[dhcp:public-custa] # network name, must be lowercase!!!
default_lease_time = 3600
max_lease_time     = 3600

   You  can  also  specify  gateway,  dns  servers, domains name and wins
   server for individual host by creating [dhcp:ip_address] section, eg.
[dhcp:213.25.209.216]
domain  = anotherdomain.com
gateway = 213.25.209.251
dns     = 213.25.209.8
wins    = 213.25.209.10
     _________________________________________________________________

4.3.8. lms-makeiptables, lms-makeipchains

   This  pair  of  script  is  being used to generate files with firewall
   rules inside. You can prepend this file with previously written header
   (ie.  containing  network-wide  rules or NAT rules) and set some fixed
   permissions to it. Those scripts does not run generated files.

   Configuration  of  those  scripts  should  be  set  in  lms.ini  file,
   [iptables] or [ipchains] section. Following parameters are valid:
     * networks
       List  of  (space  separated)  networks,  that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = public-custa public-custb
     * iptables_binary (ipchains_binary)
       Location     of     iptables     (ipchains)    binary.    Default:
       /usr/sbin/iptables (/usr/sbin/ipchains)
       Example: iptables_binary = /usr/local/sbin/iptables
     * script_file
       Output file with rules. Default: /etc/rc.d/rc.masq
       Example: script_file = /etc/rc.d/rc.firewall
     * pre_script
       File appended after cleaning existing rules and before adding new.
       Default: undefined.
       Example: pre_script = /etc/rc.d/rc.masq-pre
     * post_script
       File appended after adding rules. Default: undefined.
       Example: post_script = /etc/rc.d/rc.masq-post
     * forward_to
       List  of networks for which NAT should be set. Possible values: ""
       -  full forward, "any string" - forward off, "net1 net2" - forward
       active for selected networks. Default: full forward.
       Example: forward_to = public-custa public-custb
     * script_owneruid
       UID of file owner. Default: 0 (root).
       Example: script_owneruid = 0
     * script_ownergid
       GID of file owner. Default: 0 (root).
       Example: script_ownergid = 0
     * script_permission
       Permissions for the file. Default: 700 (rwx------).
       Example: script_permission = 700
     * snat_address
       SNAT  public  address.  If unset, for hosts with private addresses
       assigned  "-j  MASQUERADE" rule will be used. If set "-j SNAT --to
       123.123.123.123"  (with  your  IP  here)  will  be used. Only with
       lms-makeiptables. Default: not set.
       Example: snat_address = 123.123.123.123
     * tcp_redirect_ports (udp_redirect_ports)
       List  of  port forwardings in source_port:dest_port format. Can be
       used  to map ports of your firewalled machines to the ones on your
       router. Only with lms-makeipchains. Default: not set.
       Example: tcp_redirect_ports = 80:3128 25:25
     _________________________________________________________________

4.3.9. lms-etherdesc

   This  script  is  intended to create file including MAC and IP address
   pairs  from  LMS DB. MACs are being fetched in 'stripped' format, such
   is,  without  colon  separators.  This type of file might be used with
   iptraf tools.

   Configuration of lms-etherdesc should be set in lms.ini file, [ethers]
   section. Following parameters are valid:
     * networks
       List  of  (space  separated)  networks,  that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = public-custa public-custb
     * etherdesc_owneruid
       UID of file owner. Default: 0 (root).
       Example: etherdesc_owneruid = 0
     * etherdesc_file
       File location. Default: /var/lib/iptraf/ethernet.desc.
       Example: etherdesc_file = /etc/ethernet.desc
     * etherdesc_ownergid
       GID of file owner. Default: 0 (root).
       Example: etherdesc_ownergid = 0
     * etherdesc_permission
       Permissions for the file. Default: 600 (rw-------).
       Example: etherdesc_permission = 600
     _________________________________________________________________

4.3.10. lms-sendinvoices

   This script make you possible to automatically send invoices by email,
   as  email  attachments.  Invoices  are  being created in accordance to
   template  used  in  LMS-UI,  thus,  you  need  to provide username and
   password to interface for this module to work.

   This module, unlike the others, needs some extra Perl modules to work:
   Data::Dumper, LWP::UserAgent and MIME::Entity.

   Configuration  of  lms-sendinvoices  should  be  set  in lms.ini file,
   [sendinvoices] section. Following parameters are valid:
     * lms_url
       URL for your LMS installation. Default: http://localhost/lms/
       Example: lms_url = http://lms.mynet.pl
     * lms_user
       LMS user login name. Default: empty
       Example: lms_user = admin
     * lms_password
       LMS user password. Default: empty
       Example: lms_password = my_secret
     * debug_email
       Email  address  to  test  (mail will be redirected here). Default:
       undefined.
       Example: debug_email = admin@mynet.pl
     * sender_name
       Email sender name. Default: undefined.
       Example: sender_name = ASK MyNet
     * sender_email
       Email sender address. Default: undefined.
       Example: sender_email = admin@mynet.pl
     * mail_subject
       Email  subject.  %invoice  variable  will  be  replaced by invoice
       number. Default: 'Invoice No. %invoice'.
       Example: mail_subject = 'New invoice'
     * mail_body
       Email  body. %invoice variable will be replaced by invoice number.
       Default: 'Attached file with Invoice No. %invoice'.
       Example: mail_body = ''

   Script  has  also  one useful command line parameter: --fakedate (-f).
   With  this  option  you  can make that script will execute with system
   date    (in    format    YYYY/MM/DD)    other    that   current,   eg.
   --fakedate=2004/10/10.
     _________________________________________________________________

4.3.11. lms-makemacs

   This  script  is  capable  of making netfilter rules to filter traffic
   based  on  MAC  address  of the sender. For each computer one rule for
   configured  chain  is  created,  which makes test on sender IP and MAC
   addresses.  If  it  returns  success,  it returns to parent chain with
   RETURN  target.  On  the  end  of  tests two rules are appended, which
   redirects  all  http and webcache traffic to given host and port. This
   is  intended to inform customer about his debt, by running specialized
   server  on this host:port which returns administration message to each
   request. At last, the rule which blocks all traffic is added.

   Configuration  of  lms-makemacs  should be set in lms.ini file, [macs]
   section. Following parameters are valid:
     * networks
       List  of  (space  separated)  networks,  that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = public-custa public-custb
     * customergroups
       List   of  (space  separated)  customer  groups,  that  should  be
       considered   while   creating   configuration   file.   If  unset,
       configuration will include all groups.
       Example: customergroups = settlement1 settlement2
     * iptables_binary
       Location of iptables binary. Default: /sbin/iptables
       Example: iptables_binary = /usr/local/sbin/iptables
     * config_owneruid
       UID of file owner. Default: 0 (root).
       Example: config_owneruid = 0
     * config_file
       Location of the output file. Default: /etc/rc.d/rc.macs
       Example: config_file = /etc/conf.d/rc.macs
     * config_ownergid
       GID of file owner. Default: 0 (root).
       Example: config_ownergid = 0
     * config_permission
       Permissions of the file. Default: 700 (rwx------).
       Example: config_permission = 700
     * chain
       Chain  name to use (if non-standard, it will be created). Default:
       MACS.
       Example: chain = CHECKMAC
     * redirect_address
       Address  and  port,  where unmatched traffic for http and webcache
       will be redirected, in address:port format. Default: 127.0.0.1:80.
       Example: redirect_address = 192.168.1.1:3000
     * lock_noaccess
       Should  RETURN  rule  be  used  for  disconnected  (cutoff) nodes.
       Default: 0 (rules are being generated)
       Example: lock_noaccess = 1
     _________________________________________________________________

4.3.12. lms-makehosts

   This  script  generates  /etc/hosts  file,  with  IP  address  to name
   mappings.

   Configuration  of lms-makehosts should be set in lms.ini file, [hosts]
   section. Following parameters are valid:
     * networks
       List  of  (space  separated)  networks,  that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = public-custa public-custb
     * customergroups
       List   of  (space  separated)  customer  groups,  that  should  be
       considered   while   creating   configuration   file.   If  unset,
       configuration will include all groups.
       Example: customergroups = settlement1 settlement2
     * config_owneruid
       UID of file owner. Default: 0 (root).
       Example: config_owneruid = 0
     * config_file
       Location of the file. Default: /etc/hosts.
       Example: config_file = /etc/hosts
     * config_ownergid
       GID of file owner. Default: 0 (root).
       Example: config_ownergid = 0
     * config_permission
       Permissions of the file. Default: 644 (rw-r--r--).
       Example: config_permission = 600
     * config_header
       First   line   in   /etc/hosts.   Default:   127.0.0.1   localhost
       localhost.localdomain.
       Example:      config_header      =      192.168.1.1      ourserver
       ourserver.ournetwork
     _________________________________________________________________

4.3.13. lms-makewarnings

   This  script  may  be  used  to  create  file including netfiler rules
   redirecting  http  and webcache traffic to configured IP and port, for
   customers  in  debt. It uses nat table, tests source IPs and makes use
   of DNAT target.

   Configuration  of  lms-makewarnings  should  be  set  in lms.ini file,
   [warnings] section. Following parameters are valid:
     * networks
       List  of  (space  separated)  networks,  that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = public-custa public-custb
     * customergroups
       List   of  (space  separated)  customer  groups,  that  should  be
       considered   while   creating   configuration   file.   If  unset,
       configuration will include all groups.
       Example: customergroups = settlement1 settlement2
     * iptables_binary
       Location of iptables binary. Default: /sbin/iptables
       Example: iptables_binary = /usr/local/sbin/iptables
     * config_owneruid
       UID of file owner. Default: 0 (root).
       Example: config_owneruid = 0
     * config_file
       Location of the file. Default: /etc/rc.d/rc.warnings.
       Example: config_file = /etc/conf.d/rc.warnings
     * config_ownergid
       GID of file owner. Default: 0 (root).
       Example: config_ownergid = 0
     * config_permission
       Permissions of the file. Default: 700 (rwx------).
       Example: config_permission = 700
     * chain
       Custom chain to which rules will be added. Default: WARNINGS.
       Example: chain = WARN
     * redirect_address
       IP  address  and port, to which all http and webcache traffic will
       be  redirected,  for hosts to which warning was enabled in LMS-UI.
       Default: 127.0.0.1:80.
       Example: redirect_address = 192.168.1.1:3001
     * limit
       Rules are being triggered if customer balance is below this limit.
       Default: 0
       Example: limit = -85
     _________________________________________________________________

4.3.14. lms-makemessages

   This  script  is  being  used  to  create file with netfilter rules to
   redirect  all  http  and  webcache  traffic  for  customers,  who  has
   administration  messages  enabled  (aka  warnings)  to  configured  IP
   address and port. It uses nat table, tests source IPs and makes use of
   DNAT target.

   Configuration  of  lms-makemessages  should  be  set  in lms.ini file,
   [messages] section. Following parameters are valid:
     * networks
       List  of  (space  separated)  networks,  that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = public-custa public-custb
     * customergroups
       List   of  (space  separated)  customer  groups,  that  should  be
       considered   while   creating   configuration   file.   If  unset,
       configuration will include all groups.
       Example: customergroups = settlement1 settlement2
     * iptables_binary
       Location of iptables binary. Default: /sbin/iptables
       Example: iptables_binary = /usr/local/sbin/iptables
     * config_owneruid
       UID of file owner. Default: 0 (root).
       Example: config_owneruid = 0
     * config_file
       Location of the file. Default: /etc/rc.d/rc.messages.
       Example: config_file = /etc/conf.d/rc.messages
     * config_ownergid
       GID of file owner. Default: 0 (root).
       Example: config_ownergid = 0
     * config_permission
       Permissions of the file. Default: 700 (rwx------).
       Example: config_permission = 700
     * chain
       Custom chain to which rules will be added. Default: MESSAGES.
       Example: chain = MESG
     * redirect_address
       IP  address  and port, to which all http and webcache traffic will
       be  redirected,  for hosts to which warning was enabled in LMS-UI.
       Default: 127.0.0.1:80.
       Example: redirect_address = 192.168.1.1:3002
     _________________________________________________________________

4.3.15. lms-fping

   This  script  probes nodes activity and writes its status to database.
   Fast  program  fping  is  being  used to scan, with "-ar1" parameters.
   First,  list  of  nodes  is  prepares, and then fping is executed. For
   returned  hosts  date and time will be stored into DB, so availability
   can be visualized in interface.

   Configuration  of  lms-fping  should  be  set in lms.ini file, [fping]
   section. Following parameters are valid:
     * networks
       List  of  (space  separated)  networks,  that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = public-custa public-custb
     * fping_binary
       Location of fping binary. Default: /usr/sbin/fping
       Example: fping_binary = /usr/local/sbin/fping
     * temp_file
       Location  of temporary file, where list of hosts for fping will be
       stored.  After  script  execution,  this file is removed. Default:
       /tmp/fping_hosts.
       Example: temp_file = /tmp/hosts
     _________________________________________________________________

4.3.16. lms-rtparser

   This  script  is  a  backend  to  Helpdesk  system,  which  should  be
   integrated  into  your mail server configuration. It intercepts emails
   sent   to   queue   (as  defined  in  email  address  field  of  queue
   configuration),  parses  its  content  and  puts ticket into database,
   confirming  this  operation  in  email  to  reporter.  In  subject  of
   confirmation  ticket  ID  will  be  placed.  If  email with this ID is
   received  again,  it  will  be  placed  in  existing  ticket  history,
   otherwise  new ticket number will be created. Any files in the message
   will be detached and stored in directory defined with mail_dir option.

   Unlike   other   Perl   modules,   this   one  additionally  requires:
   MIME::Parser  and  MIME::Words  from  MIME-Tools  package  along  with
   Net::SMTP and Text::Iconv.

   This  script  might be installed in several ways. One way is to create
   shell  script  which  reads  content  of  users'  mailboxes  and calls
   lms-rtparser  for  each  mail  (can  be  done  with formail). But more
   elegant,  faster  and  convenient  method is to integrate it with your
   mail  server. Below you can find example on how to setup Postfix using
   header_checks.
# main.cf file:
header_checks = regexp:/etc/postfix/header_checks

# header_checks file:
/^To:.*address@domain.*/ FILTER filter:dummy

# master.cf file:
filter unix - n n - 10 pipe
      -flags=Rq user=nobody argv=/path/to/lms-rtparser

   Above  method  is  valid  for Postfix version equal or newer than 2.0.
   Earlier versions doesn't support FILTER in header_checks. You can work
   around this by using procmail:
# main.cf file:
mailbox_command = /usr/bin/procmail

# in user directory (for whom mails should be routed via helpdesk);
# .forward file:
"|IFS=' ' && exec /usr/bin/procmail -f - || exit 75 #YOUR_USERNAME"

# .procmailrc file:
:0 c
   * ^To.*address@domain
   | /bin/lms-rtparser

:0 A
$DEFAULT

   Next example shows how to connect parser to Exim, using system filter:
# exim.conf file:

system_filter_pipe_transport = address_pipe

# system_filter.txt file:

if $recipients is "queue_email@domena.pl"
then
     pipe "/path/to/lms-rtparser -q queue id"
endif

   Note

        Messages create in lms-ui may be directed to parser, instead of just
        being written to database. If you prefer this behavior turn on
        helpdesk_backend_mode option in [phpui] section of lms.ini file.

   Configuration  of  lms-rtparser  should  be  set in lms.ini file, [rt]
   section. Following parameters are valid:
     * default_queue
       ID of the queue, to which requests should be sent if not specified
       on  command  line.  If  not set queue will be guessed according to
       recipient  address.  Command  line  -q  will override this option.
       Default: undefined.
       Example: default_queue =
     * mail_from
       Sender address for confirmations. If undefined, queue address will
       be used, to which ticket was assigned. Default: empty.
       Example: mail_from = rt@net.pl
     * mail_from_name
       Sender name for confirmations. Default: undefined.
       Example: mail_from_name = 'BOK SuperLAN'
     * autoreply_subject
       Confirmation subject. You can use replacement variables here: %tid
       -  ticket  id  and %subject - request subject. Default: "[RT#%tid]
       Receipt of request '%subject'".
       Example: autoreply_subject = '[RT#%tid] Helpdesk confirmation'
     * autoreply_body
       Confirmation  body. You can use replacement variables here; %tid -
       ticket  id  and %subject - request subject. Default: 'Your request
       was  registered in our system.\nTicket identifier RT#%tid has been
       assigned  to  this  request.\nPlease,  place  string  [RT#%tid] in
       subject field of any\nfurther mail relating to this request.\n.'
       Example: autoreply_body = ''
     * smtp_server
       SMTP server to be used for sending emails. Default: localhost.
       Example: smtp_server = smtp.bigpro.com
     * mail_dir
       Directory  where  attachments should be saved. This directory will
       be  accessed  for  read/write  both  by rtparser user and your Web
       Server  user. If undefined attachments won't be recorded. Default:
       undefined.
       Example: mail_dir = /usr/local/lms/mail
     * tmp_dir
       Temp  directory.  By  default it will be taken from environment or
       set to /tmp.
       Example: tmp_dir = /home/user/tmp
     * auto_open
       This will force reopening closed/dead ticket if request is sent to
       it's ID. Default: Off.
       Example: auto_open = 1
     * newticket_notify
       If  enabled  script will send notification about new ticket to all
       users with rights for current queue. Default: Off.
       Example: newticket_notify = 1
     * lms_url
       This link, pointing to corresponding ticket page in UI is appended
       to     the     notification    about    new    ticket.    Default:
       http://localhost/lms/.
       Example: lms_url = https://lms.domain.pl/
     _________________________________________________________________

Chapter 5. Configuration file generator (lms-mgc)

   LMS-MGC  is "magical" configuration file generator. With some efforts,
   you  can  create  virtually  any configuration file using it (ie. zone
   definition file for BIND)
     _________________________________________________________________

5.1. Installation

   LMS-MGC  has  its  own  configuration  file:  lms-mgc.ini.  You should
   install  script by moving it to /usr/sbin directory. LMS-MGC should be
   used in two either ways: scheduled from cron (eg. hourly)
0 * * * *       /usr/sbin/lms-mgc 1 > /dev/null

   or  called  from  LMS  'Reload' menu. Second setup requires sudo to be
   used.  Unfortunately this method requires you to add user to sudo, and
   set in configuration section [phpui]

   reload_type = exec

   reload_execcmd = sudo /usr/sbin/lms-mgc

   LMS-MGC has following command line options:
-C, --config-file=/path/lms-mgc.ini alternative configuration file
                                    (default: /etc/lms/lms-mgc.ini);
-i, --instances=name                instance name (number) to launch, without reading
                                    lms-mgc.ini configuration, ie. -i "name1 name2"
-h, --help                          shows help;
-v, --version                       shows version number;
-q, --quiet                         shows only errors during execution;
-d, --debug                         verbose information for each IP;
     _________________________________________________________________

5.2. Configuration

   Configuration of LMS-MGC is held in lms-mgc.ini file.
     _________________________________________________________________

5.2.1. Section [database] - database setup

     * type
       Database  type.  Currently only 'mysql' is 100% supported, however
       there  seems  to  be  no  significant  problems  with  'postgres'.
       Default: mysql
       Example: type = mysql
     * host
       Database  host.  Usually localhost, but you can set it to anything
       (IP,   domain,   path  to  socket  in  'localhost:/path/to/socket'
       format). Default: localhost
       Example: host = localhost
     * user
       Database  user. In most cases (if you followed this documentation)
       it  should  be  'lms'.  If you want to use privileged account, you
       should  enter  'root'  (MySQL  on  *nices),  'mysql'  (on  PLD) or
       'postgres' (PostgreSQL). Default: root
       Example: user = mysql
     * password
       Database password. Default: empty.
       Example: password = secret_password
     * database
       Database name. Default: lms.
       Example: database = lms
     _________________________________________________________________

5.2.2. Section [mgc] - list of instances

   Significant parts of configuration are placed in section [mgc] and its
   derivative  sections.  In  [mgc]  alone  you  can  use  the  following
   parameter:
     * instances
       List of instances (separated by spaces).
       Example: instances = dhcp firewall squid

   Note

        You can also place instances variable in any derivative instance
        section. See below.
     _________________________________________________________________

5.2.3. Section [mgc:xxx] - instance configuration

   Each  instance  has  its  name  and  its  configuration  is created by
   creating derivative section of name [mgc:name], eg. [mgc:mydaemon]

   All of those sections may include following configuration options:
     * instances
       This  variable  allows you to group a list of other instances (eg.
       instances  = ins1 ins2 ins3), and then call your mgc with 'lms-mgc
       -i  mydaemon' instead of 'lms-mgc -i "ins1 ins2 ins3"'. If you use
       this variable all other settings in this section will be ignored.
       Example: instances = dns1 dns2 dns3
     * outfile
       Output   file,  where  instance  structured  dump  will  be  saved
       (instance will quit instantly if this variable is not set).
       Example: outfile = /etc/somefile
     * append
       It  allows  you  to define to not overwrite outfile, but append to
       its end instead.
       Example: append = 1
     * outfile_perm
       Permissions for output file. Default: 600 (-rw-------)
       Example: outfile_perm = 700
     * outfile_owner
       UID of output file owner. Default: 0
       Example: outfile_owner = 0

       Warning

               You have to provide numerical UID, not username!
     * outfile_group
       GID of output file owner. Default: 0
       Example: outfile_group = 0

       Warning

               You have to provide numerical GID, not group name!
     * header_file
       Filename,  that  should  be prepended at beginning of output file.
       Default: unset
       Example: header_file = /etc/lms/myservice_header
     * header
       String,  which should be put at beginning of output file. Default:
       unset
       Example: header = option1 = blah\noption2 = blab-la

       Note

            You should use \n as line separator. You may omit line separator at
            the end of last line.
     * networks
       >List  of  (space  separated)  networks, that should be considered
       while  creating  configuration  file. If unset, configuration will
       include all networks.
       Example: networks = cust1-publ cust2-publ cust3-priv

   Mgc  script  now  loops  for  each  network and performs the following
   tasks:
     * network_header
       String,  which  should  be  put  at  beginning of network section.
       Default: empty
       Example:  network_header  = network %ADDR/%MASK { # Config section
       for %NAME
     * dst_networks
       List  of  destination  network names, for which dst_network_header
       variable (see below) will be used. Default: all
       Example: dst_networks = main coalloc
     * dst_network_header
       Lets you to set destination networks header.
       Example: dst_network_header = \tallow to %DADDR/%DMASK;
     * network_body
       This  parameter  is  parsed  after  network  headers and before IP
       addresses loop.
       Example: network_body = \tnodes {

   Mgc  script  now  loops into below rules for each IP address for given
   range.  It  takes  each IP address and checks if a rule is defined for
   this  address,  if  yes - it executes first rule that matches. Matches
   are being parsed in specific order, as described below:
     * ignore
       Lets   you   setup   list   of  addresses  (in  address/prefix  or
       address/netmask form, space separated) which should be skipped.
       Example: ignore = 192.168.0.100/32
     * node(IP)
       Allows  you to add line for given IP address. IP address should be
       provided in parenthesis. Each section may have unlimited number of
       such options.
       Example: node(192.168.0.20) = ??
     * allnodes
       Adds line for each non-ignored IP address.
       Example: allnodes = ??
     * allexistnodes
       Adds  line  for  each  IP address that is 'owner' by a computer in
       database.
       Example: allexistnodes = ??
     * netdevnode
       Adds line for each IP address of network device.
       Example: netdevnode = ??
     * grantednode_priv
       Adds  line for each IP address with 'connected' status in database
       (parsed only for private address classes).
       Example: grantednode_priv = \t\tnode %NAME (%IP/%MAC) unique %ID;
     * grantednode_publ
       Adds  line for each IP address with 'connected' status in database
       (parsed only for public address classes).
       Example: grantednode_publ = \t\tnode %NAME (%IP/%MAC) unique %ID;
     * deniednode_priv
       Adds  line  for  each  IP  address  with  'disconnected' status in
       database (parsed only for private address classes).
       Example: deniednode_priv = node %NAME (%IP/%MAC) unique %ID deny;
     * deniednode_publ
       Adds  line  for  each  IP  address  with  'disconnected' status in
       database (parsed only for public address classes).
       Example: deniednode_publ = node %NAME (%IP/%MAC) unique %ID deny;
     * dhcpnode_priv
       Adds  line  for  each IP address within DHCP dynamic range (parsed
       only for private address classes).
       Example: dhcpnode_priv = node unknown (%IP) reject;
     * dhcpnode_publ
       Adds  line  for  each IP address within DHCP dynamic range (parsed
       only for public address classes).
       Example: dhcpnode_publ = node unknown (%IP) reject;
     * freeip_priv
       Adds line for each IP address that is not occupied by any computer
       in database (parsed only for private address classes).
       Example: freeip_priv = node unknown (%IP) lock_as_unused;
     * freeip_publ
       Adds line for each IP address that is not occupied by any computer
       in database (parsed only for public address classes).
       Example: freeip_publ = node unknown (%IP) lock_as_unused;
     * default_priv
       Default  line,  which  is  inserted  when  none  of grantednode or
       deniednode  matches  for given IP address (parsed only for private
       address classes)
       Example: default_priv = node unknown (%IP) lock_as_intruder;

       Note

            Mgc automatically detects if given address belongs to private or
            public network.
     * default_publ
       Default  line,  which  is  inserted  when  none  of grantednode or
       deniednode  matches  for  given IP address (parsed only for public
       address classes)
       Example: default_publ = node unknown (%IP) lock_as_intruder;

   Mgc  now  is ready to append final part of the file and execute system
   command.
     * network_footer
       Adds line for currently processed network.
       Example: network_footer = ??
     * footer_file
       Filename,  that  should  be  appended  at  the end of output file.
       Default: unset
       Example: footer_file = /etc/lms/myservice_footer
     * footer
       String,  which  should  be put at the end of output file. Default:
       unset
       Example: footer = # End.
     * post_exec
       System command that should be executed after saving output file.
       Example: post_exec = killall -HUP mydaemon
     _________________________________________________________________

5.2.4. Configuration variables

   You  can  use the following templates in your configuration variables.
   They all will be substituted with appropriate data from LMS database.

   Computer templates:
     * %IP - IP address
     * %PUBIP - second (public) IP address
     * %PIN - PIN of customer who owns node
     * %ID - ID of computer
     * %MAC - MAC address
     * %SMAC - MAC address, in lowercase and without colon separators
     * %OWNER - owner's ID
     * %CUSTOMER - owner's lastname and name
     * %NAME - computer name, in uppercase
     * %name - computer name, in lowercase
     * %INFO - computer description
     * %PASSWD - node password
     * %UPRATE - guaranteed upload rate
     * %DOWNRATE - guaranteed download rate
     * %UPCEIL - maximum upload rate
     * %DOWNCEIL - maximum download rate
     * %CLIMIT - limit of concurrent connections
     * %PLIMIT - maximum number of packets per second
     * %1  %2  %3  %4  - consecutive (left to right) decimal octets of IP
       address
     * %NID - network ID where computer belongs
     * %NNAME - network name, in uppercase
     * %nname - network name, in lowercase
     * %NADDR - network address
     * %NIFACE - network interface
     * %NMASK - network mask
     * %NGATE - network gateway IP address
     * %NDNS - primary DNS server IP address
     * %NDNS2 - secondary DNS server IP address
     * %NDOMAIN - domain name of the network
     * %NWINS - WINS server IP address
     * %NDHCPS - first IP address of dynamic DHCP range
     * %NDHCPE - last IP address of dynamic DHCP range

   Network templates (for sections relevant to networks only):
     * %ID - network ID
     * %NAME - network name, in uppercase
     * %name - network name, in lowercase
     * %ADDR - network IP address
     * %IFACE - network interface
     * %MASK - network IP mask
     * %GATE - network gateway IP address
     * %DNS - primary DNS server IP address
     * %DNS2 - secondary DNS server IP address
     * %DOMAIN - domain name of the network
     * %WINS - WINS server IP address for the network
     * %DHCPS - first IP address of dynamic DHCP range for the network
     * %DHCPE - last IP address of dynamic DHCP range for the network

   Note

        Additionally, dst_network_header variable may include above templates
        prepended with D (ie. %DADDR, %dname) to get data relevant to
        destination networks.

   Templates which can be used everywhere:
     * %DATE - date in YYYYMMDD format;
     * %TIME - time in HHMM format;
     * %TIMES - time in HHMMSS format;
     * %UTIME - time in unix timestamp format;
     _________________________________________________________________

5.3. Examples of use

   Configuration  and implementation of lms-mgc might seem quite complex,
   so  we  provide  small example. Below you can find rules to create and
   execute quite simple ipchains firewall.

   Example 5-1. Lms-mgc: Example instance

   You  should  start  with creating new mgc section in lms-mgc.ini, with
   relevant  name ('ipchains') and put a simple masquerade rules, per IP,
   inside:
[mgc:ipchains]
outfile           = /etc/rc.d/rc.masq
outfile_perm      = 700
header            = #!/bin/sh\n/sbin/ipchains -F\n/sbin/ipchains -X\n/sbin/ipchains -P forward DENY
grantednode_priv  = /sbin/ipchains -A forward -s %IP -j MASQ
post_exec         = /etc/rc.d/rc.masq

   You can also add your ipchains subsection to main mgc section, so that
   it executes it by default:
[mgc]
instances         = ipchains

   If  you run lms-mgc now, without any arguments, you should have simple
   script /etc/rc.d/rc.masq generated and already executed.
     _________________________________________________________________

Chapter 6. LMS Daemon

6.1. Basics

   This  C  daemon was developed to aid management of your services. It's
   responsible for starting appropriate modules, each performing specific
   task.  Each module makes configuration files based on its template and
   data from LMS database and manages (restarting) selected services on a
   server.  Modules  can  also  collect statistics, check hosts activity,
   account payments or notify debtors about their charges.
     _________________________________________________________________

6.1.1. Requirements

   LMS Daemon requires:
     * LMS user interface installation
     * libmysqlclient shared library (included in full MySQL installation
       or  respective "devel" package) or libpq shared library in case of
       PostgreSQL database use.
     * libdl shared library (present in every modern distribution)
     * C compiler (gcc-2.95.x or higher)
     * ggnotify module needs libgadu library and header files
     * parser module needs flex and bison (version 1.875 or newer).
     _________________________________________________________________

6.1.2. Installation

   You  have  to  setup some configure options prior to compilation, that
   can  be  listed with --help flag of ./configure script (default values
   shown in brackets):
  --help                help
  --enable-debug0       SQL queries logging (disabled)
  --enable-debug1       events logging (disabled)
  --with-pgsql          enables using of PostgreSQL database (disabled)
  --with-mysql          enables using of MySQL database (enabled)
  --prefix=PREFIX       program and modules install directory (/usr/local)
  --libdir=DIR          location of database libraries (/usr/lib)
  --incdir=DIR          location of database header files (/usr/include)
  --inifile=FILE        configuration file - disables online configuration

   It's  required to choose one database which you will use (--with-mysql
   or  --with-pgsql)  and  location  of  libraries supplied with database
   (--incdir,  --libdir).  You  can  use only one database. If you change
   database,  you  have  to  recompile your daemon. It's also possible to
   force  daemon to use configuration files instead of database. It can't
   use  both  files and db at the same time, you'll need to choose either
   before compilation.
# ./configure --with-pgsql --libdir=/usr/local/pgsql/lib --incdir=/usr/local/pgsql/include

   After  that you can compile and install (put daemon in directory given
   with --prefix option):
# make && make install

   Compiled  modules  (files  with  .so  extension),  found  in directory
   modules/module_name  will  be  moved to directory PREFIX/lms/lib. Main
   program goes to PREFIX/lms/bin.
     _________________________________________________________________

6.1.3. Configuration

   Configuration  for  daemon  and  modules  configuration  can be edited
   through  Reload -> Configuration menu in LMS-UI. Modules configuration
   is described later, in separate chapters concerning each module. Basic
   daemon  parameters  and  data  for  connection  to  database should be
   specified as command line options, according to following listing:
--dbhost -h host           host database is available (default: localhost)
--dbname -d db_name        database name (default: lms)
--dbuser -u user           database username (default: lms)
--dbpass -p password       database password (default: empty)
--hostname -H hostname     host name where daemon runs; name returned by hostname command is taken
                           as default but it can be overwritten; that name must correspond to the
                           one specified in hosts configuration in UI
--command -c command       shell command to execute before every database connection (default: empty)
--instance -i "instance[ ...]" list of instances to reload; other instances will be ignored
--reload -q                do reload and exit
--reload-all -r            do reload of all instances (including those with specified crontab) and exit
--foreground -f            run in foreground (don't fork)
--version -v               prints version and copyright info

   Database   connection   options  can  be  also  read  from  enviroment
   variables: LMSDBPASS, LMSDBNAME, LMSDBUSER, LMSDBHOST, LMSDBPORT.
   Note

        List of instances should contain instance names separated with spaces.

   Daemon  configuration  is  divided into hosts (which makes possible to
   configure  and  reload several different daemons installed on numerous
   hosts/routers) and configuration sections called as instances.

   Instance configuration, besides config modules params, have to contain
   the following primary options:
     * Name
       Instance  name,  unique  for  each  daemon  (host  where daemon is
       running).
       Example: system
     * Priority
       Priority number, which defines instances reload sequence.
       Example: 10
     * Module
       Module  name  (with  or  without  .so  extension).  If path is not
       specified  daemon  will search module in PREFIX/lms/lib directory,
       where modules are being placed after "make install".
       Example: /usr/lib/system.so
     * Crontab
       Module execution time specified in crontab style. All data must be
       numeric.  Following  example  executes  instance  each  5  minutes
       between  8  and  18  hour every day. If crontab is empty, instance
       will be reloaded only with UI reload. Default: empty.
       Example: */5 8-18 * * *

   Configuration changes does not require restarting daemon.
     _________________________________________________________________

6.1.4. Starting

   By default program runs in daemon mode. In this mode configuration and
   services  reload is performed on demand using 'Reload' menu in LMS-UI.
   Reload  order  and configuration checks (especially instances list and
   configuration of them) is done each minute. When daemon detects reload
   order, it runs all enabled instances. Instances with crontab specified
   will be executed at scheduled time.

   Other  way  to run daemon is disposable reload using '-q' command line
   option.  This is useful for tests, and in conjunction with '-i' option
   allows to run selected instances regardless of crontab entries for the
   rest of instances.
     _________________________________________________________________

6.2. Modules

   As we stated before daemon can only run modules and they are doing all
   the  job.  Most  modules  are  designed  to specific application, only
   'hostfile'  can  be  used to create many different configs (and manage
   numerous  services),  ie. various firewall types. Module configuration
   parameters MUST be placed in appropriate instance section.
     _________________________________________________________________

6.2.1. Modules list

   Table 6-1. List of all lmsd modules
     Name                           Description
    system                   Shell commands execution
    parser               Universal T-Script scripts parser
     dhcp                  Configuration of DHCP server
    cutoff                Disconnection of indebted users
     dns                    Configuration of DNS server
    ethers                   /etc/ethers file creation
   hostfile        Universal module (eg. making iptables rules)
    notify                  Email notify about payments
   ggnotify Gadu-Gadu (polish internet messenger) notify about payments
   payments                     Payments accounting
    oident                Configuration of oident daemon
      tc                         Making HTB rules
   traffic                Internet link usage statistics
    pinger               Users activity (online) scanning
     _________________________________________________________________

6.2.2. System

6.2.2.1. Description

   This  module  does  only  one thing: it runs given Linux shell command
   or/and SQL query. It can be useful if you want to execute some command
   or run external script while configuration is being reload, eg. one of
   scripts in LMS /bin directory. SQL command is executed first.
     _________________________________________________________________

6.2.2.2. Configuration

   You  can  define  command  strings  or  SQL  queries. Commands will be
   executed via shell, separated by semicolons:
     * sql
       SQL command. Default: empty.
       Example:  command  =  'DELETE  FROM  stats  WHERE  dt  <  %NOW%  -
       365*86400'
     * command
       Shell command(s). Default: empty.
       Example: command = 'echo -n "hello "; echo "world"'
     _________________________________________________________________

6.2.3. Payments

6.2.3.1. Description

   Module calculates subscription and solid fees for customers, basing on
   current  date.  It  should  be  executed  once  a  day.  Payments  are
   calculated  basing  on  customers  liabilities and written to database
   with  description  filled in 'comment' field. If appropriate, invoices
   are  created.  Description  of  solid  payment  is  a  combination  of
   liability and creditor name. At the end outdated liabilities are being
   removed from database.
     _________________________________________________________________

6.2.3.2. Configuration

   You can use following options for this module:
     * comment
       Description  of operation. '%period' will be replaced by start and
       end  date  of  subscription,  e.g.  '2003/10/10 - 2003/11/09', and
       '%tariff'  by name of liability. Default: 'Subscription: '%tariff'
       for period: %period'.
       Example: comment = 'Subscription %tariff'
     * up_payments
       How  should  period  in  comment  be counted - forward or backward
       relatively to date of write out. Default: yes.
       Example: up_payments = no
     * expiry_days
       Defines  number  of  days from date of liability expiration, after
       which  that  liability will be removed from database. When you set
       '0'  data will be removed immediately after date of the write out.
       Default: 30.
       Example: expiry_days = 365
     * deadline
       Payment deadline in days. Default: 14.
       Example: deadline = 21
     * paytype
       Payment type. Default: 'TRANSFER'.
       Example: paytype = 'CASH'
     _________________________________________________________________

6.2.4. Notify

6.2.4.1. Description

   Module 'notify' is designed to inform customers about their debt using
   electronic  mail.  Current  customer  balance  is  compared to 'limit'
   option,  if  it's  beneath  that limit - message will be sent. Message
   content  is  taken  from  template,  which  may  include the following
   variables:
     * %saldo - current customer balance (also %b)
     * %B - absolute value of current customer balance
     * %pin - customer PIN
     * %name - customer forename
     * %lastname - company name or customer lastname
     * %last_10_in_a_table - last 10 operations on customer account
     _________________________________________________________________

6.2.4.2. Configuration

   Configuration options for 'notify' module are presented below:
     * template
       Location of message template file. Default: empty.
       Example: template = modules/notify/sample/mailtemplate
     * file
       Location of temporary file. Default: /tmp/mail
       Example: file = /tmp/mail.txt
     * command
       Shell  command  for sending an e-mail. '%address' will be replaced
       by   customer  e-mail  address.  Default:  'mail  -s  "Liabilities
       Information" %address < /tmp/mail'.
       Example:  command  =  'mail  -s  "You  must pay or ..." $address <
       /tmp/mail.txt'
     * limit
       Message  is  sent  when customer balance will decrease below value
       defined in this option. Default: 0
       Example: limit = -20
     * debug_mail
       If set, all messages goes to this address, instead of sending them
       to customers. Useful for testing. Default: empty.
       Example: debug_mail = tester@my.net
     _________________________________________________________________

6.2.5. Ggnotify

6.2.5.1. Description

   Equivalent  of  'notify'  module  developed  to send gadu-gadu instant
   messages. Gadu-Gadu is most popular polish internet messenger.

   Module  require  libgadu  shared  library  and sources of ekg program.
   Appropriate     paths     for     them     must    be    present    in
   modules/ggnotify/Makefile before module compilation.
     _________________________________________________________________

6.2.5.2. Configuration

   Options similar to 'notify' module might be also used here:
     * template
       Location of message template file. Default: empty.
       Example: template = modules/notify/sample/mailtemplate
     * uin
       Gadu-gadu identifier number of message sender. Default: empty.
       Example: uin = 1234567
     * password
       Password for account specified by 'uin'. Default: empty.
       Example: password = "my_HURD.password"
     * limit
       Message  is  sent  when customer balance will decrease below value
       defined in this option. Default: 0
       Example: limit = -20
     * debug_uin
       If is set, all messages will go to that 'uin'. Default: empty.
       Example: debug_uin = 7654321
     _________________________________________________________________

6.2.6. Cutoff

6.2.6.1. Description

   Cutoff do change nodes status to 'disconnected' and/or enable warnings
   for  customers,  which  have  debts greater than specified limit. This
   module does not doing actual blocking of network access.
     _________________________________________________________________

6.2.6.2. Configuration

   You can use following options for 'cutoff' module:
     * limit
       Disconnection   occurs   when  customer  balance  decreases  below
       specified value. Default: 0.
       Example: limit = -20
     * command
       Specifies  system  command,  that  is  executed  if  at  least one
       customer  should  be  disconnected  or  warning should be enabled.
       Default: empty.
       Example: command = 'lmsd -qi firewall'
     * warning
       Enable warning for disconnected customer and write him WWW browser
       message  specified  in  this option. If empty, warning will be not
       enabled.   Date   in  message  is  substituted  providing  '%time'
       variable.  Default: 'Blocked automatically due to payment deadline
       override on %time".
       Example: warning = ""
     * warnings_only
       Here  you  can  to decide, if you want to use this module only for
       warnings or to actually cut people off. Default: false.
       Example: warnings_only = true
     _________________________________________________________________

6.2.7. DHCP

6.2.7.1. Description

   Module   responsible   for   management   of   DHCP   server,  creates
   configuration  file  and  restarts  service.  It's possible to execute
   other functions (programs) with 'command' option.
     _________________________________________________________________

6.2.7.2. Configuration

   Most   of   configuration   parameters   match   with  parts  of  DHCP
   configuration  file,  and  in  typical  environment  doesn't  need any
   changes:
     * file
       Location    of    DHCP   server   configuration   file.   Default:
       /etc/dhcpd.conf.
       Example: file = /etc/dhcp/dhcpd.conf
     * command
       Shell  command  executed  after  config  file  creation.  Default:
       'killall dhcpd; /usr/sbin/dhcpd'.
       Example: command = '/etc/rc.d/rc.dhcpd restart'
     * begin
       File header. Default: empty.
       Example: begin = "authoritative;"
     * end
       File footer. Default: empty.
       Example: end = ""
     * subnet_start
       Subnet  header.  '%a'  -  name,  '%m'  - mask. Default: "subnet %a
       netmask %m {\ndefault-lease-time 86400;\nmax-lease-time 86400;".
       Example:  subnet_start = "subnet %a netmask %m {default-lease-time
       3600;"
     * subnet_end
       Subnet footer. Default: "}".
       Example: subnet_end = '\t}'
     * subnet_gateway
       Subnet  gateway.  '%i'  will  be  changed  to IP address. Default:
       'option routers %i;'.
       Example: subnet_gateway = "option routers %i"
     * subnet_dns
       Subnet   DNS  servers.  '%i  -  dns  addresses.  Default:  "option
       domain-name-servers %i;".
       Example: subnet_dns = "option domain-name-servers 192.168.0.1"
     * subnet_domain
       Subnet  domain  name.  '%n'  -  name. Default: "option domain-name
       %n;".
       Example: subnet_domain = "option domain-name test.%n;"
     * subnet_wins
       WINS   servers.   '%i'  -  server  IP  address.  Default:  "option
       netbios-name-servers %i;".
       Example: subnet_wins = ""
     * subnet_range
       Subnet address range. '%s' - initial address, '%e' - end of range.
       Default: "range %s %e;".
       Example: subnet_range = "range %s %e;"
     * host
       Hosts  parameters,  where  '%n' - host name, '%m' - MAC, '%i' - IP
       address.   Default:   "\thost   %n  {\n\t\thardware  ethernet  %m;
       fixed-address %i; \n\t}".
       Example:  host  =  "host  %n  {hardware ethernet %m; fixed-address
       %i;}"
     * networks
       List  of  network  names  that should be included in configuration
       (case insensitive). Default: empty (all networks).
       Example: networks = "lan1 lan2"
     * customergroups
       List  of customers groups that should be included in configuration
       (case insensitive). Default: empty (all groups).
       Example: customergroups = "group1 group2"
     _________________________________________________________________

6.2.8. Hostfile

6.2.8.1. Description

   Module  'hostfile'  is  a  multipurpose  tool. It performs loop on all
   hosts  from  database  fetching their status (connected/disconnected),
   network  that they are connected to and groups of they owners. Because
   of  that  it  is  possible to create any firewall rules, or /etc/hosts
   file.  Data  is written to file and after that specified shell command
   is executed.
     _________________________________________________________________

6.2.8.2. Configuration

   The following templates might be used for 'grantedhost', 'deniedhost',
   'public_grantedhost'  and  'public_deniedhost'  options  replaced with
   actual data from database:
   %i - IP address,
   %ipub - public IP address,
   %id - node ID,
   %m - MAC address,
   %n - host name,
   %p - node (computer) password,
   %info - node description,
   %domain - domain,
   %net - network name,
   %gw - gateway address of network,
   %if - network's interface,
   %mask - network mask,
   %addr - network's address,
   %dns, %dns2 - DNS server addresses,
   %wins - WINS server address,
   This module has following options:
     * file
       Location of generated file. Default: /tmp/hostfile
       Example: file = /etc/rc.d/rc.firewall
     * command
       Shell command(s) executed after 'file' creation. Default: empty
       Example: command = '/bin/sh /etc/rc.d/rc.firewall'
     * begin
       File header. Default: "/usr/sbin/iptables -F FORWARD\n"
       Example: begin = "IPT=/usr/sbin/iptables \n$IPT -F FORWARD\n"
     * end
       File footer. Default: "/usr/sbin/iptables -A FORWARD -J REJECT\n"
       Example: end = "$IPT -A FORWARD -J REJECT\n"
     * grantedhost
       Line with rule(s) for connected node. Default: "/usr/sbin/iptables
       -A FORWARD -s %i -m mac --mac-source %m -j ACCEPT\n"
       Example:  grantedhost = "$IPT -A FORWARD -s %i -m mac --mac-source
       %m -j ACCEPT\n"
     * deniedhost
       Line    with    rule(s)    for    disconnected    node.   Default:
       "/usr/sbin/iptables  -A  FORWARD  -s  %i -m mac --mac-source %m -j
       REJECT\n"
       Example:  deniedhost  = "$IPT -A FORWARD -s %i -m mac --mac-source
       %m -j REJECT\n"
     * public_grantedhost
       Line  with rule(s) for connected node with specified public IP. By
       default rule specified in 'grantedhost' option.
       Example:  public_grantedhost  =  "$IPT  -A  FORWARD  -s  %i -m mac
       --mac-source  %m  -j  ACCEPT\n$IPT  -t nat -A PREROUTING -p tcp -d
       %ipub  -j  DNAT --to-destination %i\n$IPT -t nat -A POSTROUTING -s
       %i -j SNAT --to-source %ipub\n"
     * public_deniedhost
       Line  with rule(s) for disconnected node with specified public IP.
       By default rule specified in 'deniedhost' option.
       Example: public_deniedhost = ""
     * networks
       List  of  network names which members should be included in config
       (case insensitive). Default: empty (all networks).
       Example: networks = "lan1 lan2"
     * customergroups
       List  of  customer group names which members should be included in
       config (case insensitive). Default: empty (all groups).
       Example: customergroups = "group1 group2"
     * skip_dev_ips
       If  enabled  (yes,  true)  network  devices (devices that does not
       belong to customers) will be ignored (omitted). Default: yes
       Example: skip_dev_ips = no
     _________________________________________________________________

6.2.9. Traffic

6.2.9.1. Description

   'Traffic'  is  an  equivalent of 'lms-traffic' Perl script,which loads
   internet  link stats to database, from file created by user. That file
   must   have   format:   host_IP  upload  download.  More  informations
   (including  how  to  make  such  file)  can  be  found in chapter with
   lms-traffic description.
     _________________________________________________________________

6.2.9.2. Configuration

   There is only one available option and it's mandatory:
     * file
       Location     of     file    with    firewall    stats.    Default:
       /var/log/traffic.log
       Example: file = /tmp/log
     _________________________________________________________________

6.2.10. Tc (HTB)

6.2.10.1. Description

   Generate  script  containing iptables and tc rules for traffic control
   ie.  band  and  customer  connections  limits.  Rules for nodes can be
   freely  defined  and  used  not only for traffic control. Principle of
   operation of this module is following: First of all all customers data
   is  being retrieved. Totals for limitations (uprate, downrate, upceil,
   downceil,  connection  limit)  are being calculated for each customer.
   Then,  loop  is performed to check networks and groups (if specified).
   If  limit  values  are  not  zeroes  rules  are  written  to file with
   variables  replacement.  The following variables can be used in rules:
   %name  -  host  name,  %i  - IP address, %m - MAC, %uprate, %downrate,
   %upceil,  %downceil,  %plimit,  %climit, and %x - integer counter with
   initial value of 100 incremented by one for each node.

   Default  policy  for  creating  HTB  class  is one class per all nodes
   belonging    to    each    customer.    It   can   be   changed   with
   'one_class_per_host' option.

   Default  configuration  assumes  that  your  system  supports  HTB and
   iptables  with modules limit, connlimit, mark and ipp2p. You can patch
   kernel  or  use  sources available at www.inet.one.pl (polish project,
   site in PL).
     _________________________________________________________________

6.2.10.2. Configuration

   There  are  basic  options  like  groups  of customers, file, command,
   networks  and  extra  options  which  are define tc and firewall rules
   available  to  use. Default config is designed for 512/128 kbit limits
   and 100mbit links.
     * file
       Location of file. Default: /etc/rc.d/rc.htb.
       Example: file = /tmp/rc.htb
     * command
       Shell   command   executed   after  file  creation.  Default:  "sh
       /etc/rc.d/rc.htb start".
       Example: command = "chmod 700 /tmp/rc.htb; /tmp/rc.htb start"
     * begin
       Script header. Default:
"#!/bin/sh
IPT=/usr/sbin/iptables
TC=/sbin/tc
LAN=eth0
WAN=eth1
BURST="burst 30k"

stop ()
{
$IPT -t mangle -D FORWARD -i $WAN -j LIMITS >/dev/null 2>&1
$IPT -t mangle -D FORWARD -o $WAN -j LIMITS >/dev/null 2>&1
$IPT -t mangle -F LIMITS >/dev/null 2>&1
$IPT -t mangle -X LIMITS >/dev/null 2>&1
$IPT -t mangle -F OUTPUT
$IPT -t filter -F FORWARD
$TC qdisc del dev $LAN root 2> /dev/null
$TC qdisc del dev $WAN root 2> /dev/null
}

start ()
{
stop
$IPT -t mangle -N LIMITS
$IPT -t mangle -I FORWARD -i $WAN -j LIMITS
$IPT -t mangle -I FORWARD -o $WAN -j LIMITS
# incoming traffic
$IPT -t mangle -A OUTPUT -j MARK --set-mark 1
$TC qdisc add dev $LAN root handle 1:0 htb default 3 r2q 1
$TC class add dev $LAN parent 1:0 classid 1:1 htb rate 99000kbit ceil 99000kbit quantum 1500
$TC class add dev $LAN parent 1:1 classid 1:2 htb rate   500kbit ceil   500kbit
$TC class add dev $LAN parent 1:1 classid 1:3 htb rate 98500kbit ceil 98500kbit prio 9 quantum 1500
$TC qdisc add dev $LAN parent 1:3 esfq perturb 10 hash dst
# priorities for ICMP, TOS 0x10 and ports 22 and 53
$TC class add dev $LAN parent 1:2 classid 1:20 htb rate 50kbit ceil 500kbit $BURST prio 1 quantum 1500
$TC qdisc add dev $LAN parent 1:20 esfq perturb 10 hash dst
$TC filter add dev $LAN parent 1:0 protocol ip prio 2 u32 match ip sport 22 0xffff flowid 1:20
$TC filter add dev $LAN parent 1:0 protocol ip prio 2 u32 match ip sport 53 0xffff flowid 1:20
$TC filter add dev $LAN parent 1:0 protocol ip prio 1 u32 match ip tos 0x10 0xff flowid 1:20
$TC filter add dev $LAN parent 1:0 protocol ip prio 1 u32 match ip protocol 1 0xff flowid 1:20
# server -> LAN
$TC filter add dev $LAN parent 1:0 protocol ip prio 4 handle 1 fw flowid 1:3

# outgoing traffic
$TC qdisc add dev $WAN root handle 2:0 htb default 11 r2q 1
$TC class add dev $WAN parent 2:0 classid 2:1 htb rate 120kbit ceil 120kbit
# priorities for ACK, ICMP, TOS 0x10, ports 22 and 53
$TC class add dev $WAN parent 2:1 classid 2:10 htb rate 60kbit ceil 120kbit prio 1 quantum 1500
$TC qdisc add dev $WAN parent 2:10 esfq perturb 10 hash dst
$TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip protocol 6 0xff \
match u8 0x05 0x0f at 0 match u16 0x0000 0xffc0 at 1 match u8 0x10 0xff at 33 flowid 2:10
$TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip dport 22 0xffff flowid 2:10
$TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip dport 53 0xffff flowid 2:10
$TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip tos 0x10 0xff flowid 2:10
$TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip protocol 1 0xff flowid 2:10
# server -> Internet
$TC class add dev $WAN parent 2:1 classid 2:11 htb rate 30kbit ceil 120kbit prio 2 quantum 1500
$TC qdisc add dev $WAN parent 2:11 esfq perturb 10 hash dst
$TC filter add dev $WAN parent 2:0 protocol ip prio 3 handle 1 fw flowid 2:11
$TC filter add dev $WAN parent 2:0 protocol ip prio 9 u32 match ip dst 0/0 flowid 2:11
       Example: begin = "#!/bin/bash\n$TC=/usr/local/sbin/tc\n"
     * end
       Script footer. Default:
}

case "$1" in
    'start')
     start
    ;;
    'stop')
     stop
    ;;
    'status')
     echo "WAN Interface"
     echo "============="
     $TC class show dev $WAN | grep root
     $TC class show dev $WAN | grep -v root | sort | nl
     echo "LAN Interface"
     echo "============="
     $TC class show dev $LAN | grep root
     $TC class show dev $LAN | grep -v root | sort | nl
    ;;
    *)
     echo -e "\nUsage: rc.htb start|stop|status"
    ;;
esac
       Example: end = ""
     * one_class_per_host
       Specify  htb  class  creation  policy. By default all computers of
       customer  will  be  placed in one class. Setting it to 'true' will
       effect  in  that  rules specified in host_htb_up and host_htb_down
       will  be  generated  for  all customer's computers (with different
       value  of  '%x').  Rules host_mark_down, host_mark_up, host_plimit
       and  host_climit  are  generated  for each node regardless of this
       option setting. Default: false
       Example: one_class_per_host = 1
     * host_mark_down
       Mark rule for each offline computer. Default:
# %n
$IPT -t mangle -A LIMITS -d %i -j MARK --set-mark %x
       Example: host_mark_down = ""
     * host_mark_up
       Mark rule for each computer. Default:
$IPT -t mangle -A LIMITS -s %i -j MARK --set-mark %x
       Example: host_mark_up = ""
     * host_htb_down
       Rules for each computer executed when uprate and downrate value is
       above zero. Default:
$TC class add dev $LAN parent 1:2 classid 1:%x htb rate %downratekbit ceil %downceilkbit $BURST prio 2 quantum 1500
$TC qdisc add dev $LAN parent 1:%x esfq perturb 10 hash dst
$TC filter add dev $LAN parent 1:0 protocol ip prio 5 handle %x fw flowid 1:%x
       Example: host_htb_down = ""
     * host_htb_up
       Rules for each computer executed when uprate and downrate value is
       above zero. Default:
$TC class add dev $WAN parent 2:1 classid 2:%x htb rate %upratekbit ceil %upceilkbit $BURST prio 2 quantum 1500
$TC qdisc add dev $WAN parent 2:%x esfq perturb 10 hash dst
$TC filter add dev $WAN parent 2:0 protocol ip prio 5 handle %x fw flowid 2:%x
       Example: host_htb_up = ""
     * host_climit
       Rule with simultaneous TCP connections limit. Executed when climit
       value is above zero. Default:
$IPT -t filter -I FORWARD -p tcp -s %i -m connlimit --connlimit-above %climit -m ipp2p --ipp2p -j REJECT
       Example:  host_climit = "$IPT -t filter -I FORWARD -p tcp -s %i -m
       connlimit --connlimit-above -j REJECT"
     * host_plimit
       Rule with limiting of packets in time unit (here second). Executed
       when plimit value is above zero. Default:
$IPT -t filter -I FORWARD -p tcp -d %i -m limit --limit %plimit/s -m ipp2p --ipp2p -j ACCEPT
$IPT -t filter -I FORWARD -p tcp -s %i -m limit --limit %plimit/s -m ipp2p --ipp2p -j ACCEPT
       Example: host_plimit = ""
     * networks
       List  of  network  names  that should be included in configuration
       (case insensitive). Default: empty (all networks).
       Example: networks = "lan1 lan2"
     * customergroups
       List  of  customer groups that should be included in configuration
       (case insensitive). Default: empty (all groups).
       Example: customergroups = "group1 group2"
     _________________________________________________________________

6.2.11. Dns

6.2.11.1. Description

   Configuration  of named zones. This is one of most complicated modules
   to  setup.  It creates zone files for each network and zone definition
   entries  in  named.conf  on  the  basis  of  template  files.  Example
   templates are placed in /modules/dns/sample directory.
     _________________________________________________________________

6.2.11.2. Configuration

     * forward-patterns
       Directory with zone templates. Default: forward.
       Example: forward-patterns = /dns/patterns/forward
     * reverse-patterns
       Directory with reverse zone templates. Default: reverse.
       Example: reverse-patterns = /dns/patterns/revers
     * generic-forward
       Default  template.  It  will  be  used  if  directory specified by
       'forward-patterns'  doesn't contain a file with name corresponding
       to network domain name. Default:
       modules/dns/sample/forward/generic.
       Example: generic-forward = /dns/patterns/forward
     * generic-reverse
       Default  template.  It  will  be  used  if  directory specified by
       'reverse-patterns'  doesn't contain a file with name corresponding
       to network IP address. Default:
       modules/dns/sample/reverse/generic.
       Example: generic-reverse = /dns/patterns/forward
     * forward-zones
       Directory      for      generated     zone     files.     Default:
       modules/dns/sample/out/forward.
       Example: forward-zones = /dns/forward
     * reverse-zones
       Directory    for    generated   reverse   zone   files.   Default:
       modules/dns/sample/out/reverse.
       Example: reverse-zones = /dns/reverse
     * host-reverse
       Line  in  reverse  zone  file  for each computer of given network.
       Default: "%n IN A %i\n".
       Example: host-reverse = "\t %n IN A %i\n"
     * host-forward
       Line in zone file for each computer of given network. Default: "%c
       IN PTR %n.%d.\n".
       Example: host-forward = "\t %c IN PTR %n.%d.\n"
     * conf-pattern
       Location  of main template for server configuration file. Default:
       modules/dns/sample/named.conf.
       Example: conf-pattern = /dns/patterns/named.conf
     * conf-output
       Location of main configuration file. Default: /tmp/named.conf.
       Example: conf-output = /etc/named.conf
     * conf-forward-entry
       Entry  for  each  zone  in main configuration file. Default: 'zone
       "%n" {\ntype master;\n file "forward/%n"; \nnotify yes; \n}; \n'.
       Example:  conf-forward-entry  =  'zone  "%n"  {  \n\ttype  master;
       \n\tfile "forward/%n"; \n\tnotify yes; \n}; \n'
     * conf-reverse-entry
       Entry  for  each reverse zone in main configuration file. Default:
       'zone  "%c.in-addr.arpa"  {  \ntype  master;  \nfile "reverse/%i";
       \nnotify yes; \n}; \n'.
       Example:  conf-revers-entry  =  'zone "%c.in-addr.arpa" { \n\ttype
       master; \n\tfile "reverse/%i"; \n\tnotify yes; \n}; \n'
     * command
       Shell command executed after files creation. Default: empty.
       Example: command = "killall -HUP named"
     * networks
       List  of  network  names  that should be included in configuration
       (case insensitive). Default: empty (all networks).
       Example: networks = "lan1 lan2"
     * customergroups
       List  of  customer  (user)  groups  that  should  be  included  in
       configuration (case insensitive). Default: empty (all groups).
       Example: customergroups = "group1 group2"
     _________________________________________________________________

6.2.12. Ethers

6.2.12.1. Description

   This module creates configuration for system ARP table. Setting option
   'dummy_macs'   will   put   mac   address  00:00:00:00:00:00  for  all
   disconnected computers.
     _________________________________________________________________

6.2.12.2. Configuration

   Basic options:
     * file
       Location of output file. Default: /etc/ethers.
       Example: file = /tmp/ethers
     * command
       Shell command to execute after config file creation. Default: 'arp
       -f /etc/ethers'.
       Example: command = ""
     * dummy_macs
       If   you  set  to  'yes',  disconnected  computers  will  get  MAC
       '00:00:00:00:00:00'. Default: "no".
       Example: dummy_macs = yes
     * networks
       List  of  network  names  that should be included in configuration
       (case insensitive). Default: empty (all networks).
       Example: networks = "lan1 lan2"
     * customergroups
       List   of  customer  groups  names  that  should  be  included  in
       configuration (case insensitive). Default: empty (all groups).
       Example: customergroups = "group1 group2"
     _________________________________________________________________

6.2.13. Oident

6.2.13.1. Description

   Module  for  oidentd  configuration.  Basically it can be created with
   hostfile  module,  but  here  you have ready-made default settings for
   this purpose.
     _________________________________________________________________

6.2.13.2. Configuration

   And here are the options of oident:
     * begin
       Text inserted on the beginning of file. Default: empty.
       Example: begin = "#Auto-generated\n"
     * end
       Text inserted on the end of file. Default: empty.
       Example: end = ""
     * host
       Line of text for each of computers. Default: "%i\t%n\tUNIX".
       Example: host = "%i %n WINDOWS"
     * file
       Configuration file. Default: /etc/oidentd.conf.
       Example: file = /tmp/identd.conf
     * networks
       List of networks. Default: empty (all networks).
       Example: networks = 'lan1 lan2'
     * command
       Shell command(s) to execute after file creation. Default: empty.
       Example: command = "killall -HUP oidentd"
     _________________________________________________________________

6.2.14. Pinger

6.2.14.1. Description

   Module  pinger  is  an equivalent of lms-fping Perl script, however it
   has  some fundamental differences. It doesn't need external program to
   check hosts availability and work with use of ARP protocol and thus it
   can  perform  network scanning about 2 times faster. Also there are no
   problems  with  hosts with ping response disabled or firewalled. After
   scanning,  last-seen time is set for all online hosts in database used
   to illustrate hosts activity on nodes list and network map.

   Note

        Pinger for work use interface names, so (e.g. if you are using ip
        command) you'll need to label interfaces in your system (ip addr add
        ... label ...). Also remember, don't use a dots or dashes in interface
        names (ip allows that, but such a name is not usable for pinger).
     _________________________________________________________________

6.2.14.2. Configuration

   Pinger has only one config option:
     * networks
       List of network names. Default: empty (all networks).
       Example: networks = 'lan1 lan2'
     _________________________________________________________________

6.2.15. Parser

6.2.15.1. Introduction

   Parser  module is based on a scripting language T-Script which primary
   purpose  is  to  generate  text files. It can be useful for processing
   templates  with  some additional data retrieved from data sources like
   SQL  databases or text files. In lmsd's module contents of scripts are
   stored  in  database,  so they can be edited via LMS-UI. In the future
   parser should replace almost all lmsd modules.

   T-Script language is described in section T-Script.

   Before  compilation ensure that you have in your system packages bison
   (at least 1.875 version) and flex.
     _________________________________________________________________

6.2.15.2. Configuration

   Parser has following options:
     * script
       Contents of script. Default: empty.
       Example: script = '{var=1}variable var={var}'
     * file
       Location of output file. Default: empty.
       Example: file = /tmp/parser.out
     * command
       Shell command to execute after script compilation. Default: empty
       Example: command = "sh /tmp/parser.out"
     _________________________________________________________________

6.3. T-Script

6.3.1. Introduction

   T-Script  is a scripting language which primary purpose is to generate
   text  files.  It  can  be  useful  for  processing templates with some
   additional data retrieved from data sources like SQL databases or text
   files.

   Before  compilation ensure that you have in your system packages bison
   (at least 1.875 version) and flex.
     _________________________________________________________________

6.3.2. Syntax

   T-Script language syntax is based on other popular languages like C or
   JavaScript  with  little  changes  made  to  make  writting  templates
   simpler. Additional commands should be written inside { } parenthesis.
   Data  outside curly brackets will be writed to output file (or ommited
   if  file  was  not  specified).  All expressions, variables, commands,
   function  names  are  case-sensitive.  To  separate expressions inside
   parenthesis use semicolon sign.
     _________________________________________________________________

6.3.2.1. Expressions and operators

     * Literal inside quotes.
       Example: "some literal"
     * Number.
       Example: 1234
     * Value of variable "var".
       Example: var
     * N-th element of array "var".
       Example: var[n]
     * Subvariable "n" of variable "var".
       Example: var.n
     * Value of expression inside parenthesis.
       Example: ( expression )
     * Null  keyword.  Prescribe  not  defined value. Useful for checking
       that some value was or wasn't defined.
       Example: variable = null
     * Comparisions. Returns logical result of expressions comparision.
       Example:
expression1 == expression2;
expression1 != expression2;
expression1 < expression2;
expression1 > expression2;
expression1 <= expression2;
expression1 >= expression2;
     * Binary operators. Sum and product.
       Example: expression1 | expression2
       Example: expression1 & expression2
     * Logical operators.
       Example: expression1 || expression2
       Example: expression1 && expression2
       Example: ! expression
     * Strings concatenation. When both expression values haven't numeric
       type   treats   expressions   as   strings   and  performs  string
       concatenation.
       Example: expression1 + expression2
     * Arithmetic  operators. Evaluates to result of arithmetic operation
       on two expression values.
       Example:
expression1 + expression2;
expression1 - expression2;
expression1 * expression2;
expression1 / expression2;
expression1 % expression2;
     * Unary increment/decrement operators.
       Example: expression++
       Example: expression--
       Example: ++expression
       Example: --expression
     * Bit shift operators.
       Example: expr1 >> expr2
       Example: expr1 << expr2
     * String  comparision  with  regular  expression.  Evaluates to 1 if
       expression  expr1  value match with regular expression expr2, else
       0.
       Example: expr1 =~ expr2
     _________________________________________________________________

6.3.2.2. Comments

     * C-style comment.
       Example: /* this is a comment - it can be also multiline */
     _________________________________________________________________

6.3.2.3. Commands

     * Assignment. Assigns expression value to specified variable.
       Example: variable = expression
     * Conditional  statement.  Executes  statement only if expression is
       true.  Second  form  executes  statement1 if expression is true or
       statement2 if expression is false.
       Example:
if ( expression ) statement /if
if ( expression ) statement1 else statement2 /if
       Text  between  command  blocks  is  treated  as  a  command so the
       following example is correct:
Some text
{if (a==1)}
a equals 1
{else}
a doesn't equal 1
{/if}
       You can put backslash between command block and end of line to eat
       \n symbol and keep normal text flow. For example:
Some text
{if (a==1)}\
a equals 1
{else}\
a doesn't equal 1
{/if}\
     * Iterative  loop.  Executes  first  expr1  as  loop  initialization
       command.  Then  executes statement while expr2 is true. At the end
       of each iteration expr2 is evaluated.
       Example: for ( expr1 ; expr2 ; expr3 ) statement /for
     * Construct  foreach.  This simply gives an easy way to iterate over
       arrays. foreach works only on arrays, and will issue an error when
       you  try  to  use  it on a variable with a different data type. It
       loops  over  the  array given by array. On each loop, the value of
       the  current  element  is assigned to value and the internal array
       pointer is advanced by one (so on the next loop, you'll be looking
       at the next element).
       Example: foreach ( value in array ) statement /foreach
     * While  loop.  Executes  statement(s)  repeatedly,  as  long as the
       expression  evaluates  to  true.  The  value  of the expression is
       checked  each  time  at the beginning of the loop, so even if this
       value  changes  during  the  execution of the nested statement(s),
       execution will not stop until the end of the iteration.
       Example: while ( expression ) statement /while
     * break. This command ends execution of the current loop structure.
       Example:
{for (i = 0; i < 10; i++)}\
{if (i == 5)}{break}{/if}\
: {i}
{/for}\
     * continue.  continue  is used within looping structures to skip the
       rest  of  the current loop iteration and continue execution at the
       condition evaluation and then the beginning of the next iteration.
       Example:
{for (i = 0; i < 10; i++)}\
{if (i == 5)}{continue}{/if}\
: {i}
{/for}\
     * exit. This command terminates the current script.
       Example:
{if ( var > 0 )
exit;
/if}
     _________________________________________________________________

6.3.2.4. Functions

   Functions  have two calling forms: with brackets ({function(var)}) and
   without brackets ({function {var}}).
     * string(number)
       Converts numeric variable to string value.
       Example: string(var)
     * number(string)
       Converts  string  variable  to  numeric  value. For arrays returns
       number of items in array.
       Example: number(var)
     * typeof(variable)
       Type checking. Returns type name of variable, e.g. string, number,
       array, null.
       Example: typeof(var)

   In script above functions can be used like that:
{x = 5}x = {x}
{var = "3"}var = {var}
x + var = {x + var}
x + var = {number(var) + x}
x + var = {string(x) + var}
x is type of {typeof(x)}
var is type of {typeof(var)}
     _________________________________________________________________

6.3.3. Extensions

   Extensions  are  tscript  library  supplements. That are functions and
   predefined variables (constants), wich can be used in scripts.
     _________________________________________________________________

6.3.3.1. Exec

   Shell  commands  execution  is  possible with exec(). You can run many
   commands separated by semicolons in one function call.
     * exec(commands)
       Shell commands execution.
       Example: exec("rm -f /")
     _________________________________________________________________

6.3.3.2. String

   String consists basic functions for strings operations.
     * trim(string)
       Deleting  of  whitespace  signs  from the beginning and the end of
       string.
       Example: trim(" aaa ")
     * replace(pattern, replacement, string)
       This  function  scans string for matches to pattern, then replaces
       the  matched  text  with  replacement.  Pattern  can  be a regular
       expression.
       Example: replace(":", "-", mac)
       Example: replace("[a-z]", "-", "Text")
     * explode(separator, string)
       Returns  an  array  of  strings,  each  of which is a substring of
       string  formed  by splitting it on boundaries formed by separator.
       Separator can be a string or POSIX's regural expression.
       Example: explode(":", "aaa:bbb:ccc")
       Example: explode("[ ]+", "aaa bbb ccc")
     _________________________________________________________________

6.3.3.3. Sysinfo

   Extension  with name Sysinfo consist functions for retriving data from
   system.
     * date([format_string])
       Current   date   and   time   formated  according  to  the  format
       specification. Default format is '%Y/%m/%d'. Conversion specifiers
       are  introduced  by a '%' character You can read about all of them
       in `man strftime`.
       Returned  object consist predefined subvariables year, month, day,
       hour, minute, second.
       Example:
{date("%s") /* returns current unix timestamp */}
{t = date()}
{t.month /* returns current month number */}
     * systype
       System  type  constant.  Returns  "unix"  or  "win32" according to
       system where program's working.
       Example:
{if (systype == "unix")}\
{exec echo executing command}\
{else}\
no shell
{/if}\
     _________________________________________________________________

6.3.3.4. File

   This extension is destined for basic file operations.
     * file(filename)
       Script  output  redirection. Redirects script output to file. Data
       will be appended to specified file.
       Example: {file file_name} commands {/file}
     * fileexists(filename)
       If file exists returns 1, else 0.
       Example:
{if fileexists(file)}{deletefile(file)}{/if}
     * deletefile(filename)
       File deletion.
       Example: deletefile("/tmp/file.txt")
     * readfile(filename)
       Creates array where every element is separated line of file.
       Example: readfile("/tmp/file.txt")
     * getfile(filename)
       Returns file contents.
       Example: getfile("/tmp/file.txt")
     * listdir(directory)
       Returns list of files (and subdirectories) in array. Every element
       contains subvariable 'size' with file size in bytes.
       Example: listdir("/home/alec")

   Listing below presents example script with use of all file functions.
{list = listdir("/home/alec/lms/doc")}
{for (x = 0; x < number(list); x++) }\
{list[x]}--{list[x].size}
{/for}\
{file "/home/alec/file.txt"}
Line 1
Line 2
{/file}\
{f = readfile /home/alec/file.txt}\
{for (i = 0; i < number(f); i++) }\
line {i}: {f[i]}\
{/for}\
{f = getfile /home/alec/file.txt}\
{f}
{deletefile /home/alec/file.txt}\
     _________________________________________________________________

6.3.3.5. Syslog

   Extension  with  name  Syslog consist function for sending messages to
   system logger. Also includes logs priority (level) definitions.
     * syslog(string [, level])
       Sends  message  specified  by  string.  Second,  optional argument
       specify  logs  priority.  Default  priority is LOG_INFO (see man 3
       syslog).
       Example:
syslog("message", LOG_ERR);
syslog("message");
     _________________________________________________________________

6.3.3.6. Net

   In  this  extension  are included two functions (with lowercase names)
   destined to IP addresses and subnet masks operations.
     * mask2prefix(mask_string)
       Returns number of bits in subnet mask.
       Example: mask2prefix("255.255.255.0")
     * ip2long(address_string)
       Changes octal IP address to long number.
       Example: ip2long("192.168.0.1")
     * long2ip(number)
       Changes long number to IP address octal format (xxx.xxx.xxx.xxx).
       Example: long2ip(variable)
     * broadcast(address_string, mask_string)
       Calculates  broadcast  address  from specified IP address and mask
       (any mask format).
       Example: broadcast("192.168.0.1", "255.255.255.0")
     _________________________________________________________________

6.3.3.7. SQL

   SQL  extension implements functions for database operations. Allows to
   run SQL commands.
     * SQL commands: SELECT, INSERT, DELETE, UPDATE, CREATE, DROP.
       Example:
{SELECT * FROM table}
{INSERT INTO table VALUES(1)}
{DELETE FROM table}
{UPDATE table SET column=1}
{CREATE TABLE foo (bar integer) }
{DROP TABLE foo}
     * rows(sql_query)
       Returns SQL result rows count. Use it for non-select commands.
       Example: rows("SELECT * FROM table")
     * escape(string)
       Escapes a string for use within an SQL commands.
       Example: SELECT * FROM table WHERE name={escape(variable)}

   Extension closely connected with LMS. Makes possible to create scripts
   without  of  LMS's  database  structure knowledge. Contains predefined
   constants, which consists data from database. Query defined in program
   is  executed  when  constant  is  used first time. Constants names are
   uppercase.  Each  constant is an array with rows indexed starting from
   zero,   and   each   row   consist  subvariables  accessible  by  name
   (lowercase).
     * CUSTOMERS - customers list:

       id - customer ID
       lastname - customer lastname
       name - customer name
       status - status
       address - address
       zip - postal code
       city - city
       email - email address
       phone1, phone2, phone3 - phone numbers
       ten - tax exempt number
       ssn - security serial number
       info - additional informations
       message - warning contents
       warning - warning status (status of all customer's nodes summary)
       access - accessibility status (status of all customer's nodes summary)
       balance - customer's balance
     * NODES - nodes list (and network devices addresses):

       id - node ID
       owner - customer name and lastname
       ownerid - customer ID ('0' for devices)
       name - node (device's address) name
       access - status: connected/disconnected (1/0)
       warning - warnings status: enabled/disabled (1/0)
       netdev - device ID, to which is connected
       lastonline - last activity timestamp
       info - additional informations
       message - warning message contents
       mac - MAC address
       passwd - password
       ip - IP address
       ip_pub - public IP address
       linktype - connection type (0-cable, 1-air)
     * NETWORKS - networks list:

       id - network ID
       name - network name
       address - IP address
       mask - subnet mask (xxx.xxx.xxx.xxx)
       prefix - number of bits in mask
       size - network size (number of addresses)
       interface - interface name
       gateway - gateway address
       dns - primary DNS server
       dns2 - secondary DNS server
       wins - WINS server
       domain - domain name
       dhcpstart - start of DHCP range
       dhcpend - end of DHCP range
     _________________________________________________________________

6.3.4. Example Scripts

   Let's  begin  from simple script creating file /etc/hosts with list of
   computers (and devices) IPs and names list.

   Example 6-1. Parser: Creating /etc/hosts file
{result = SELECT name, inet_ntoa(ipaddr) AS ip FROM nodes}\
127.0.0.1       localhost
{for (r=0; r<number(result); r++)}\
{result[r].name}\t{result[r].ip}
{/for}\

   How  to  create  debtors  list?  It's  easy  with  use  of  predefined
   constants.

   Example 6-2. Parser: Debtors list
{
for (r=0; r<number(CUSTOMERS); r++)
    if (CUSTOMERS[r].balance < 0)
}\
{CUSTOMERS[r].lastname} {CUSTOMERS[r].name}\t{CUSTOMERS[r].balance}
{
    /if
/for
}\

   List  of  ethernet  hosts  desriptions  for iptraf. Here the format of
   hardware address is specific. It must be writed without separators.

   Example 6-3. Parser: Ethernet hosts descriptions for iptraf.
{list = SELECT LOWER(mac) AS mac, UPPER(name) AS name, inet_ntoa(ipaddr) AS ipfrom nodes}\
{for(i=0; i<number(list); i++)}\
{replace(":","",list[i].mac)}:{list[i].name} {list[i].ip}
{/for}

   In  next  example  we're  create  file  with  hosts  ethernet hardware
   addresses to IP addresses mappings, used by arp program. Hosts with no
   access gets dummy MACs.

   Example 6-4. Parser: Ethers file for arp
{if(number(NODES))}\
{       if(fileexists("/etc/ethers"))}\
{               deletefile("/etc/ethers")}\
{       /if}\
{       for (i=0; i<number(NODES); i++)}\
{               if (number(NODES[i].access))}\
{                       nodes[i].mac}\t{NODES[i].ip}
{               else}\
{                      }00:00:00:00:00:00\t{NODES[i].ip}
{               /if}\
{      /for}\
{/if}\

   Next  example  is  longer. Here we are using especially 'exec'. Script
   sends e-mails to customers with balance less than specified limit.

   Example 6-5. Parser: Notify module replacement
{limit = 0}
{dt = date()}
{customers = SELECT customers.id AS id, email, pin, name, lastname,
        SUM((type * -2 +7) * cash.value) AS balance
        FROM customers
        LEFT JOIN cash ON customers.id = cash.customerid AND (cash.type = 3 ORcash.type = 4)
        WHERE deleted = 0 AND email!=''
        GROUP BY customers.id, name, lastname, email, pin
        HAVING SUM((type * -2 +7) * cash.value) < {limit}}

{for(i=0; i<number(customers); i++)}

    {exec echo "NOTE: This message has been generated automatically.

We kindly remind that you have debt on your internet service provide account
for the amount of $ {customers[i].balance}.

If you have already regulated your subscription fees for current month, that
is {dt.month} {dt.year}, please just skip this message.

If you think this message was sent to you in error, please contact our
customer service representative.

All information about payments could be also found at:
http://bigpro.com/myAccount/

If you want to regulate your account status, please contact our accountant:

Aldfert Rule
phone: 0-509031337
e-mail: alde@staff.bigpro.com

PS. Last 10 operations on your account has been attached below for your
convenience.
--------------+--------------+-----------------------------
     Date     |    Value     |           Comment
--------------+--------------+-----------------------------" > /tmp/mail}

    {last10 = SELECT comment, time, CASE WHEN type=4 THEN value*-1 ELSE value END AS value
            FROM cash WHERE customerid = {customers[i].id}
            ORDER BY time DESC LIMIT 10}

    {for(j=0; j<number(last10); j++)}

        {exec echo "{last10[j].time}|\t{last10[j].value}|\t{last10[j].comment}" >> /tmp/mail}

    {/for}

    {exec mail -s "Liabilities information" -r lms@domain.tld {customers[i].email} < /tmp/mail}

{/for}

   Next more complicated example is the traffic module replacement. Reads
   text  file  with stats from firewall counters and writes data to LMS's
   stats database.

   Example 6-6. Parser: Traffic stats.
{
log = "/var/log/traffic.log";
nodes = SELECT id, INET_NTOA(ipaddr) AS ip, INET_NTOA(ipaddr_pub) AS ip_pub FROM nodes;
if(! fileexists(log))
    exit;
/if;
lines = readfile(log);
n = number(nodes);
for (i=0; i<number(lines); i++)
    line = explode("[[:blank:]]+", lines[i]); /* file format: IP upload download */
    if ( number(line) == 3  && (line[1] > 0 || line[2] > 0) )
        for (x=0; x<n; x++)
            if (nodes[x].ip == line[0] || nodes[x].ip_pub == line[0] )
                id = nodes[x].id;
                break;
            /if;
        /for;
        if (x < n)
            INSERT INTO stats (nodeid, dt, download, upload) VALUES ({id}, %NOW%, {line[2]}, {line[
        /if;
     /if;
/for;
     _________________________________________________________________

Chapter 7. For curious

7.1. Directory tree

   Table 7-1. LMS directory tree
      Name                   Description
     backups        Backup copies of LMS database
       bin          Executable lms-* Perl scripts
     contrib           LMS user's contributions
     daemon              A.L.E.C's LMS Daemon
      devel    Developers' scripts to build LMS package
       doc                LMS Documentation
    documents             Documents archive
       img              User Interface Images
       lib         Set of LMS and Smarty libraries
     modules            User Interface Modules
     sample     Sample scripts, configs and additions
    templates            User Interface Theme
   templates_c    Smarty Theme compilation directory
     _________________________________________________________________

7.2. Database structure

   Simple  database  layout  is  provided  below.  For more details (data
   types,  fields  restrictions  and  default  values)  please  refer  to
   lms.mysql, lms.pgsql in doc/ directory.
     _________________________________________________________________

7.2.1. LMS users ('users')

   id - serial number
   login - login
   name - first and last name
   email - user's email address
   rights - binary access rights
   hosts - list of hosts allowed to login
   passwd - password to login
   lastlogindate - date of last login
   lastloginip - IP of last login
   failedlogindate - date of last failed login attempt
   failedloginip - IP of last failed login attempt
   deleted - if is deleted boolean (0/1)
     _________________________________________________________________

7.2.2. Customers ('customers')

   id - serial number
   lastname - last/company name
   name - first name
   status - customer status (3-connected, 2-awaiting, 1-prospect)
   email - email address
   phone1 - phone
   phone2 - phone
   phone3 - phone
   im - internet messenger (gadu-gadu) serial number
   pin - pin number (for authentication)
   address - street address (street, apartment, flat, etc)
   zip - zip code
   city - location (city)
   ten - tax exempt number
   ssn - social security number
   info - additional informations
   serviceaddr - correspondence address
   creationdate - record creation date
   moddate - record modification date
   creatorid - serial of LMS user who created this record
   modid - serial of LMS user last modification this record
   deleted - if is deleted from database boolean (0/1)
   message - message to be displayed if warnings enabled
     _________________________________________________________________

7.2.3. Customer groups ('customergroups')

   id - serial number
   name - group name
   description - group description
     _________________________________________________________________

7.2.4. Customer groups - continued... ('customerassignments')

   id - serial number
   customergroupid - group serial number
   customerid - customer serial number
     _________________________________________________________________

7.2.5. Networks ('networks')

   id - serial number
   name - network name
   address - IP address
   mask - network mask
   interface - network interface (eg. eth1)
   gateway - gateway IP address
   dns - IP address of dns server
   dns2 - IP address of secondary dns server
   domain - domain of the network
   wins - WINS server address
   dhcpstart - first address of dynamic DHCP range
   dhcpend - last address of dynamic DHCP range
     _________________________________________________________________

7.2.6. Computers and network devices ('nodes')

   id - serial number
   name - device name
   mac - MAC address
   ipaddr - IP address
   passwd - computer password for radius/pppoe login
   ownerid - serial number of the owner ('0' if network device)
   creationdate - creation timestamp
   moddate - last modification timestamp
   creatorid - creator's serial number
   modid - modifier's serial number
   netdev - serial number of connected network device
   linktype - type of connection (0-cable, 1-wireless)
   access - connected/disconnected (cutoff) (1/0)
   warning - should be warned with administration message? (1/0)
   lastonline - last network activity timestamp
   info - additional information
     _________________________________________________________________

7.2.7. Network devices - continued... ('netdevices')

   id - serial number
   name - name
   location - physical location
   description - device summary
   producer - manufacturer's name
   model - model number
   serialnumber - products serial number (not DB identifier)
   ports - number of connections available
     _________________________________________________________________

7.2.8. Network connections ('netlinks')

   id - serial number
   src - connection's beginning
   dst- connection's end
   type - type of connection (0-cable, 1-wireless)
     _________________________________________________________________

7.2.9. Financial operations ('cash')

   id - serial number
   time - timestamp of operation
   type - type of operation (1-payment, 0-liability)
   userid - LMS user id
   value - amount in dollars
   taxid - tax rate identifier
   customerid - customer's serial number ('0' - does not apply)
   docid - serial number for document (e.g. invoice) related to this
   operation
   itemid - document item identifier
   comment - description of operation
     _________________________________________________________________

7.2.10. Import of financial operations ('cashimport')

   id - serial number
   date - timestamp of operation
   customer - customer data
   value - amount
   taxid - tax rate identifier
   customerid - customer's serial number
   description - operation description
   hash - unique operation identifier
   closed - yes (1), if operation was moved to cash table
     _________________________________________________________________

7.2.11. Subscription fees ('tariffs')

   id - serial number
   name - subscription name
   value - amount
   taxid - tax rate identifier
   prodid - product/service classification number
   uprate - upload warranty
   upceil - upload boundary
   downrate - download warranty
   downceil - download boundary
   climit - limit of concurrent connections
   plimit - limit of packets per second
   description - description for subscription
     _________________________________________________________________

7.2.12. Custom liabilities ('liabilities')

   id - serial number
   name - liability name/description
   value - amount
   taxid - tax rate identifier
   prodid - product/service classification number
     _________________________________________________________________

7.2.13. Solid payments ('payments')

   id - serial number
   name - name
   value - amount
   creditor - creditor name
   period - interval of operation:
   daily/weekly/monthly/quarterly/annually (1/2/3/4/5)
   at - pay day
   description - description for payment
     _________________________________________________________________

7.2.14. Financial assignments ('assignments')

   id - serial number
   tariffid - subscription serial number
   liabilityid - liability serial number
   customerid - customer serial number
   period - interval of operation:
   daily/weekly/monthly/quarterly/annually (1/2/3/4/5)
   at - pay day
   datefrom - start date for assignment
   dateto - end date for assignment
   invoice - invoice writeout? (1 - yes, 0 - no)
   discount - discount percentage
   suspended - is this payment suspended? (1 - yes, 0 - no)
     _________________________________________________________________

7.2.15. Tax rates ('taxes')

   id - serial number
   value - tax value
   taxed - "is taxed" flag
   label - rate label
   validfrom - binding period start
   validto - binding period end
     _________________________________________________________________

7.2.16. Documents numbering plans ('numberplans')

   id - serial number
   template - number template (pattern)
   period - numbering time span: day/week/month/quarter/year
   doctype - document type
   isdefault - '1' if this plan is default for respondent doctype, else
   '0'
     _________________________________________________________________

7.2.17. Documents: invoices, receipts, contracts, etc. ('documents')

   id - serial number
   number - document number (%N)
   numberplanid - numbering plan identifier
   type - document type (1 - invoice, 2 - cash receipt)
   cdate - date of write out
   paytime - deadline in days
   paytype - payment method (cash/transfer/etc.)
   customerid - customer (buyer) serial number
   userid - user serial number
   name - name of customer
   address - address of customer
   ssn - SSN of customer
   ten - Tax Exempt Number of customer
   zip - zip code of customer
   city - location of customer
   closed - is document (invoice) closed (accounted)? (0/1)
   reference - document ID reference
     _________________________________________________________________

7.2.18. Non-financial documents contents ('documentcontents')

   docid - document serial number
   title - document title
   fromdate - start of binding period
   todate - end of binding period
   filename - document file name
   contenttype - file type
   md5sum - file md5 sum
   description - additional informations
     _________________________________________________________________

7.2.19. Invoices ('invoicecontents')

   docid - invoice serial number
   itemid - invoice item identifier
   value - amount
   taxid - tax rate identifier
   prodid - product/service classification number
   content - used unit (usually 'pc.')
   count - unit count
   description - description for invoice
   tariffid - subscription serial number
     _________________________________________________________________

7.2.20. Cash Receipts ('receiptcontents')

   docid - receipt serial number
   itemid - receipt item identifier
   value - amount
   description - description for receipt item
     _________________________________________________________________

7.2.21. Accounts ('passwd')

   id - serial number
   ownerid - customer serial number (0 - "system" account)
   login - login name
   password - password encrypted with crypt()
   realname - additional name
   lastlogin - last login date
   uid - account system UID (usually ownerid+200)
   home - account home directory
   type - account type (binary sum: 1-shell, 2-email, 4-www, 8-ftp)
   expdate - account expire date
   domainid - domain serial number
   createtime - account creation date
   quota_sh - shell space limits
   quota_mail - email space limits
   quota_www - www space limits
   quota_ftp - ftp space limits
     _________________________________________________________________

7.2.22. Domains ('domains')

   id - serial number
   name - domain name
   description - comments
     _________________________________________________________________

7.2.23. Aliases ('aliases')

   id - serial number
   login - account name (without domain)
   accountid - account serial number
     _________________________________________________________________

7.2.24. History ('timestamps')

   time - last modified timestamp
   tablename - name of modified table
     _________________________________________________________________

7.2.25. Bandwidth consumption statistics ('stats')

   nodeid - node serial number
   dt - timestamp
   upload - number of bytes sent
   download - number of bytes received
     _________________________________________________________________

7.2.26. Helpdesk - Request Tracking ('rtqueues')

   id - serial number
   name - queue name
   email - email account for the queue
   description - main description for the queue
     _________________________________________________________________

7.2.27. Helpdesk - Request Tracking - continued... ('rttickets')

   id - serial number
   queueid - queue serial number
   requestor - reporter name and email
   customerid - customer serial number (if reported by customer)
   subject - ticket name)
   state - status (0-new, 1-open, 2-resolved, 3-dead)
   owner - LMS user serial number (ticket owner)
   createtime - timestamp of report
     _________________________________________________________________

7.2.28. Helpdesk - Request Tracking - continued... ('rtmessages')

   id - serial number
   ticketid - ticket serial number
   userid - LMS user serial number (if ticket sender)
   customerid - customer serial number (if ticket sender)
   mailfrom - sender email
   subject - message subject
   messageid - Message-ID message header
   inreplyto - thread serial number (if threaded)
   replyto - Reply-To message header
   headers - all message headers
   body - content of message body
   createtime - date of creation/send/delivery
     _________________________________________________________________

7.2.29. Helpdesk - Request Tracking - continued... ('rtattachments')

   messageid - message serial number
   filename - name of file attachment
   contenttype - type of file
     _________________________________________________________________

7.2.30. Helpdesk - Request Tracking - continued... ('rtrights')

   id - serial number
   queueid - queue serial number
   userid - LMS user serial number
   rights - permissions (1-read, 2-write)
     _________________________________________________________________

7.2.31. LMS-UI Online Configuration ('uiconfig')

   id - serial number
   section - config section name
   var - config variable name
   value - config variable value
   description - option description or comment
   disabled - is option disabled? (0-active, 1-disabled/default)
     _________________________________________________________________

7.2.32. Timetable - events ('events')

   id - identifier
   title - title
   description - info
   note - note
   date - event date
   begintime - beginning of event
   endtime - end of event
   userid - event creator ID
   customerid - customer ID
   private - status (private/public)
   closed - is event closed? (1-yes/0-no)
     _________________________________________________________________

7.2.33. Timetable - assignments ('eventassignments')

   eventid - event identifier
   userid - user identifier
     _________________________________________________________________

7.2.34. Sessions ('sessions')

   id - session identifier
   ctime - create time
   mtime - last modification time
   atime - last access time
   vdata - verification data
   content - data
     _________________________________________________________________

7.2.35. Hosts ('hosts')

   id - identifier
   name - host name
   description - additional informations
   lastreload - last reload date
   reload - reload order
     _________________________________________________________________

7.2.36. Daemon configuration - instances ('daemoninstances')

   id - identifier
   name - instance name
   hostid - host identifier
   module - module file path and name
   crontab - time of reload
   priority - reload priority
   description - additional informations
   disabled - status (enabled/disabled)
     _________________________________________________________________

7.2.37. Daemon configuration - options ('daemonconfig')

   id - identifier
   instanceid - instance identifier
   var - option name
   value - option value
   description - additional informations
   disabled - status (enabled/disabled)
     _________________________________________________________________

7.2.38. Database information ('dbinfo')

   keytype - type
   keyvalue - value
     _________________________________________________________________

7.3. Configuration file format

   Configuration file default location is /etc/lms/lms.ini. It's intended
   to  be  central  configuration  for  LMS-UI, LMS-MGC and other scripts
   (exluding  lmsd  daemon).  However variable format for Perl scripts is
   more restricted than for PHP.
     _________________________________________________________________

7.3.1. Comments

   Configuration  file  parsers skip all lines that begin with '#' or ';'
   sign.  You can also append comments to the end of the lines containing
   valid variables and sections , followed by that signs.
     _________________________________________________________________

7.3.2. Sections, variables, values

   Configuration  options  are  grouped in sections. Name of the section,
   which  is  build  with alphanumerical signs must be enclosed in square
   brackets.  Their  name  should  be unique in the span of configuration
   file.

   Sections  and  parameters  should  be  placed  one per line. Parameter
   consists  of  key (variable name) and value (variable content). Key is
   name  of  configuration  parameter,  built  from alphanumerical signs.
   Value  should  be  placed in the same line, after equality sign. If it
   contains  any  special  characters  it should be placed into quotes or
   apostrophes.

   Example 7-1. Format of configuration options
[section]
key =  value
variable1 = "some text"
para_meter = 'i am "para_meter" variable in apostrophes'

[section_1]                    # you can comment here
key = "text with specials: \t and ;"     ; you can comment here either
; and this is comment all line long
key = "A.L.E.C's LMS Daemon is the best"
# option = disabled
     _________________________________________________________________

7.3.3. Perl scripts variables

   Configuration  for  use  by Perl scripts is someway restricted, due to
   restrictions  of  Config::IniFiles  module  which parses configuration
   file.  Comments  must be placed in new lines only. Values shouldn't be
   enclosed  into  apostrophes or quotes and are being read from equality
   sign since the end of line.
     _________________________________________________________________

7.4. Filling DB with random data

   If  you  want  to test your LMS installation instantly you can fill it
   with some random data using 'genfake' module.

   To  generate data you should, once logged in, open in your Web browser
   URL   http://ourserver.org/lms/?m=genfake  and  write  how  many  user
   records  should  be  created in the text box. After you hit enter, the
   whole  content  of  database  will  be  erased and populated with some
   random data. You might get some database errors while generating data,
   as this algorithm is not truly random.
   Note

        For proper creation of dependences you should only run this module on
        empty database.
   Warning

           All data will be erased from database, except LMS users
           (Administrators) records.
     _________________________________________________________________

7.5. Access levels

   This description intended audience are LMS developers. :)

   Originally  access  levels  were  supposed  to  be  defined by various
   letters. It was assumption made at LMS-0.4, but it never actually took
   place.  Due  to  it's presence in 1.0, I've racked my brain bout using
   64-character  string.  So,  in  64-character long field, there is just
   256-bit hexadecimal number. Each character might describe maximum of 4
   bits  (4*64  =  256, which is a number of valid combinations). Turning
   some  level  on effects in turning some bit on. Then, if "full access"
   has  index  0  in  lib/accesstable.php, 0 bit will be set to 1, so the
   number  will  be  1.  Levels may have numbers (indices) from 0 to 255.
   This  is  not final boundary, because using more letters and chars you
   can   expand  to  6  bytes  per  char  easily,  which  gives  you  384
   combinations.
     _________________________________________________________________

7.6. Restrictions

   Each  system has its restrictions. Some of ours are inherited from SQL
   engine  being  used.  Some from assumptions (nearly) knowingly made by
   developers. Those are current restrictions:
     _________________________________________________________________

7.6.1. LMS project related

   Amount  of  money  (in  'cash' table) was stored (as of lms-1.1) as 32
   integer  value,  so  if you had 5000 users you might had problems in 8
   years or so. Nowadays (since lms-1.1.7 Hathor) we use more appropriate
   type [ decimal (9.2), with 2 significant places after dot and 9 numers
   for whole sum] and the maximum is 9'999'999.99 (sum of all in/out cash
   operations).  Procedures  converting  numbers  to  words  are  able to
   process numbers as big as 10^18.
     _________________________________________________________________

7.6.2. Unicode-related problems

   We  are  switching to Unicode in UI and databases. Right now there are
   known  problems.  When  you have to use SQL with poor Unicode support,
   you  should  use  UI converting capabilities. (PHP only? watch out for
   perl  scripts!).  In following example (file lms.ini) we have database
   in LATIN2 (aka ISO-8859-2) format.
[database]
user     = lms
password = lms12354
server_encoding = latin2 ; if DB is not encoded in Unicode
     _________________________________________________________________

7.6.3. SQL engine related

     * MySQL
          + Database size:
            Following MySQL documentation ("How Big Can MySQL Tables Be?"
            in  chapter  "Table  size"), MySQL 3.22 is restricted 4GB per
            table.  Since  3.23  restriction is 8 million terabytes (2^63
            bytes).  It's  worth  to  mention, however, that some systems
            have filesystem level, usually at 2 or 4 GB.
          + Number of records:
            True  informations  can  be  obtained,  by  issuing (in mysql
            shell):
mysql> show table status;

...| Avg_row_length | Data_length | Max_data_length | Index_length |
...|             44 |       24136 |      4294967295 |        19456 |
            See that free space is about 175 000 time more than currently
            used,  so  until you plan to have 100000 users, you're pretty
            safe in this matter :-)
     * PostgreSQL
          + Database size:
            PostgreSQL  stores  data  in  8kB blocks. Number of blocks in
            bound  to  32-bit number with sign, which gives maximum table
            size  of 16 terabytes. Filesystem restrictions are avoided by
            keeping data in slices, 1GB each.
          + Number of records:
            PostgreSQL does not have row number limit for tables, however
            COUNT  returns  32-bit  number,  so  for tables longer that 2
            billions of records this function will return wrong value (at
            least in version 7.1).
     _________________________________________________________________

Chapter 8. Extensions

   This  chapter  describes  additional modules and implementations which
   extend  LMS functionality. Some of them need to be adjusted for user's
   own need, some of them integrate with LMS-UI interface. All extensions
   are located in contrib subdirectory.
     _________________________________________________________________

8.1. Customer account

8.1.1. Intro

   In  contrib/customer  directory  you  can find example solution, which
   displays  financial  balance and contact information for a given user,
   which makes possible for your customers to view this data themselves.

   Script  checks  IP  address  for  request  and  displays data which is
   relevant to computer's owner.

   For  proxy  users, people not checking from home or to those who don't
   intend  that  they  children/spouse/workers  are  able  to  see  their
   financial data there's "Customer account 2" module.
     _________________________________________________________________

8.1.2. Installation

   You should copy those files to any path and make it accessible to your
   Web   Server,   or   set  appropriate  alias  (eg.  Alias  /myAccount/
   /var/www/lms/contrib/customer)  and  put  correct  path  to lms.ini in
   index.php.
     _________________________________________________________________

8.2. Customer account 2

8.2.1. Intro

   In  contrib/customer_otherip  directory  you  can  find  equivalent of
   "Customer account" module, which does not authorize user basing on his
   IP address, but requires login. Authentication can be performed basing
   on user's PIN number and phone - or alternatively ID or contact number
   - as username, see balanceview.php and authentication.inc files).

   Script  shows user his balance and contact information, and, with help
   of contrib/formularz_przelewu_wplaty gives user a possibility to print
   money order for his debts.

   It also allows aquiring and printing invoices by customers
     _________________________________________________________________

8.2.2. Installation

   All   installation   is   limited   to  setup  of  sys_dir  option  in
   [directories] section of lms.ini file and linking img/ with UI icons.
     _________________________________________________________________

8.3. SQL Panel

8.3.1. Intro

   In  contrib/sqlpanel  directory  you can find module which enables you
   direct  access  to  LMS database, based on direct queries. Results are
   being shown as table, along with execution time. It's also possible to
   print query results.

   Number of instantly displayed records is 50 by default. You can change
   this  limit  in  sqlpanel_pagelimit  variable  in  section  [phpui] of
   configuration.
     _________________________________________________________________

8.3.2. Installation

   Installation is limited to copying needed files into LMS tree: sql.php
   should  be  placed into modules directory, and sql.html, sqlprint.html
   into templates. After those steps are done, you're able to access this
   module via http://lms.domain.pl/?m=sql.
     _________________________________________________________________

8.4. Squid redirector

8.4.1. Intro

   This  tiny  set  of  tools  allows  you to display users their warning
   messages (and cut access to entire Web off, it needed) in very elegant
   way, namely using squid Proxy Server. Obviously to make this work, all
   users  should  be  forced to use proxy (or transparent proxy should be
   setup).

   Key  component is redirector. It's responsible for user redirection to
   programmed  message,  when  warn  flag  is  set  in  database  for his
   computers.  URL  to  programmed message is not subject of redirection,
   which  enables user's browser to download images. If computer has warn
   flag  set,  it's  redirected to message, where he has a choice to mark
   this  message  as  read.  After  that  user  is taken back to original
   (requested)  URL. If given computer is disconnected (cutoff) it always
   redirects  him  to  the  message, without any possibility to "quit" to
   Web. For more information, please see README file.
     _________________________________________________________________

8.4.2. Installation

   Let's start from configuring squid (squid.conf):
redirector_bypass on
redirect_program /path/to/lms-squid

   That  informs  squid  that  it should use our redirector for each URL.
   Next  step is to configure our redirector. Open lms-squid file in your
   favorite editor and change this line:
my $configfile = '/etc/lms/lms.ini';

   ...to reflect location of your lms.ini file. The rest of configuration
   is  being set in actual lms.ini file, where we should add [redirector]
   section and define URL of our programmed message:
[redirector]
redirect        = http://net-komp.net.pl

   At  last,  we copy files index.php, message.html to the directory that
   should  serve  a  message to users and linking to lms images directory
   (img).
     _________________________________________________________________

Chapter 9. FAQ

   9.1. My network device map does not show up. What to do?
   9.2. How to add two computers with the same IP?
   9.3. How to add two computers with the same MAC?
   9.4. I see following error: Can't locate Config/IniFiles.pm in @INC
          ...What should I do?

   9.5. I make few corrections. Do you accept any patches?
   9.6. What is current version of LMS, which one i should use?
   9.7. How to unsubscribe from the mailing list?
   9.8. What is a limit of network devices on the map?
   9.9. Insecure $ENV{BASH_ENV} while running -T switch...
   9.10. How to get list of customers without assigned tariffs?

   9.1. My network device map does not show up. What to do?

   First  you  should check your Web Server logs. Usually it's helpful to
   increase  amount  of  memory  PHP  may  use  in memory_limit option of
   php.ini file.

   9.2. How to add two computers with the same IP?

   There  is no such possibility. Additionally, authors have no plans for
   such  a  functionality  in  near  future. However you might try to use
   unofficial patch multiip which could be found in contrib directory.

   9.3. How to add two computers with the same MAC?

   Check documentation. You probably look for allow_mac_sharing = 1.

   9.4.  I  see  following error: Can't locate Config/IniFiles.pm in @INC
   ...What should I do?

   It's  likely  that  you don't have required Perl modules installed. In
   this  case  it's  Config::IniFiles that is missing. The easiest way to
   install  Perl  modules  is  to  use CPAN extension, eg. perl -MCPAN -e
   'install Config::IniFiles'.

   9.5. I make few corrections. Do you accept any patches?

   You   should  post  it  to  our  mailing  list.  Attach  your  patches
   (preferably  to  current  cvs  version, use unified diff format) along
   with short description on what your code does. Eg.
$ cd lms
$ cvs -z7 diff -u > /tmp/my_patch.patch

   If you're interested into joining LMS developers team, please apply on
   the  mailing list. You should however first make a good impression and
   stay  on  the  list  for  a  while, that may prove your skills, before
   asking us for cvs account.

   9.6. What is current version of LMS, which one i should use?

   LMS adopts versioning from Linux kernel. Thus, in LMS-x.y.z we have: x
   - major version number, y - stable if number is even, unstable if odd,
   z  -  minor  version number. Therefore, if stable version appears, eg.
   1.4.0 you shouldn't expect any new functionality in this branch, 1.5.x
   is  created instead, where new features are being put, and which might
   not function well, or might be unstable.

   Archive of all LMS versions can be found here: lms.rulez.pl/download

   You  should  be  aware that -RC version (release canditate) are not as
   stable as one could expect. i.e. vestion 1.4.3 should be prefered over
   1.6-rc3. "-RC" are not to be used in production areas.

   9.7. How to unsubscribe from the mailing list?

   Information  about  it is enclosed in all messages headers. You should
   send "unsubscribe" entitled message to lms-en-request@lists.rulez.pl.

   9.8. What is a limit of network devices on the map?

   Map  creation  algorithm  isn't perfect. You can connect maximum of 24
   computers  to  one  network  device (this number at max will appear on
   map,  you can connect more devices of course). Similarly, each network
   device  might  be  connected to the other 24 devices, but usually this
   number  is  subject  of change (it might be smaller), depending on how
   devices  are  placed  on the map. When this number is exceeded you may
   observe  bogus  connections  going  beyond  the  map,  or less likely,
   problems with generating map at all.

   9.9. Insecure $ENV{BASH_ENV} while running -T switch...

   Quoted  error  appears  while  you  run Perl scripts that needs to use
   external  programs  on  some systems. Problem description and possible
   solutions  are  described in Perl manual (man perlsec) in "Cleaning Up
   Your Path" chapter. Simplest solution is to remove -T switch, which is
   responsible for the error, from the first line of the script.

   9.10. How to get list of customers without assigned tariffs?

   You can do this with following SQL query:
SELECT customers.id, customers.lastname, customers.name
FROM customers
LEFT JOIN assignments ON customers.id = customerid
WHERE deleted = 0
     AND (customerid IS NULL
     OR NOT ((datefrom <= UNIX_TIMESTAMP() OR datefrom = 0)
     AND (dateto > UNIX_TIMESTAMP() OR dateto = 0)))

   and PostgreSQL version:
SELECT customers.id, customers.lastname, customers.name
FROM customers
LEFT JOIN assignments ON customers.id = customerid
WHERE deleted = 0
     AND (customerid IS NULL
     OR NOT ((datefrom <= EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)) OR datefrom= 0)
     AND (dateto > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)) OR dateto = 0)))
