doc
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
parent directory.. | ||||
LMS - LAN Management System 1.11-git
[logo-small.png]
LMS Developers
Copyright © 2001-2013 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. Documents
3.9. Hosting
3.10. Messages
3.11. Reload
3.12. Stats
3.13. Helpdesk
3.14. Timetable
3.15. 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. Userpanel
9.1. About
9.2. Installation
9.3. Configuration
9.4. Graphical themes (styles)
9.5. Modules
10. 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
Tomasz 'Chilek' Chilinski
Konrad 'kondi' Rzentarzewski
Grzegorz 'Ceho' Chwesewicz
* C Code:
Aleksander 'A.L.E.C' Machniak
Marcin 'Lexx' Krol
Tomasz 'Chilek' Chilinski
* Perl Code:
Lukasz 'Baseciq' Mozer
Michal 'DziQs' Zapalski
Maciej 'agaran' Pijanka
Krzysztof 'hunter' Drewicz
Tomasz 'Chilek' Chilinski
Grzegorz 'Ceho' Chwesewicz
* Design:
Lukasz 'Baseciq' Mozer
* HTML, JavaScript, CSS:
Lukasz 'Baseciq' Mozer
Pawel 'Bob_R' Czerski
Pawel 'sickone' Kisiela
Tomasz 'Chilek' Chilinski
Konrad 'kondi' Rzentarzewski
Grzegorz 'Ceho' Chwesewicz
* Images:
Piotr 'Pierzak' Mierzenski
Grzegorz 'byko' Cichowski
Kuba 'kflis' Flis
Lukasz 'Baseciq' Mozer
Jakub 'Jimmac' Steiner
* 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, xajax, 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.lms.org.pl. Further emails should be sent to address
lms-en@lists.lms.org.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.lms.org.pl.
__________________________________________________________________
1.4.3. Newest version
Newest version of LMS can be downloaded from CVS repository utilizing
WWW interface at here, or with CVS tools (anonymous access, empty
password):
cvs -d :pserver:cvs@cvs.lms.org.pl:/cvsroot login
cvs -d :pserver:cvs@cvs.lms.org.pl:/cvsroot co lms
cvs -d :pserver:cvs@cvs.lms.org.pl:/cvsroot logout
__________________________________________________________________
1.4.4. Changelog
Information 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 5.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 and/or ming (network map only),
* mysql or mysqli or pgsql (for db support),
* iconv, mbstring (LMS uses unicode)
* PEAR::Mail (which require PEAR::Net_SMTP and PEAR::Net_Sockets) for
mailing.
__________________________________________________________________
2.2.3. Database Server
MySQL server in version 5.x is supported. Probably LMS won't work
correctly with older versions.
PostgreSQL in version 8.4.x or higher is supported.
__________________________________________________________________
2.2.4. Smarty Library
LMS-UI requires Smarty library (http://www.smarty.net) in version 3.0
or higher. 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 (www.lms.org.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://www.lms.org.pl/download/stable/lms-x.x.x.tar.gz
$ tar zxf lms-x.x.x.tar.gz
Smarty library is included in LMS package but if you are using CVS you
have to install Smarty yourself. After download copy contents of
Smarty's lib directory into /lib/Smarty or use /devel/smarty_install.sh
script which will do this for you.
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!).
Warning
It's absolutely required for LMS to disable register_globals PHP's
option.
Recommended setting in php.ini (or httpd.conf for LMS virtual host
directory):
mbstring.func_overload = 7
register_globals = off
max_execution_time = 60 ; or more
memory_limit = 32M ; or more
__________________________________________________________________
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. 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 CHARACTER SET utf8 COLLATE utf8_polish_ci;
mysql> GRANT USAGE ON lms.* TO lms@localhost;
mysql> GRANT ALL ON lms.* TO lms@localhost IDENTIFIED BY '[your_password]';
mysql> flush privileges;
__________________________________________________________________
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 require PostgreSQL 8.4 or higher. If you have not installed
PostgreSQL server, you can 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 &
Warning
Applies to version <= 9.1.x: It's required to add in postgresql.conf:
custom_variable_classes = 'lms'
__________________________________________________________________
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 -DPRS lms
$ /usr/local/pgsql/bin/createdb -E UNICODE -O lms lms
__________________________________________________________________
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. Other settings are stored in database and could
be changed by user interface.
__________________________________________________________________
2.6.1. Section [database] - Database Settings
* type
Database driver type. Currently are supported 'mysql' or 'mysqli'
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
__________________________________________________________________
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_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
* traffic stats
* messaging (email, sms)
* Helpdesk (RT) administration
* Helpdesk (RT) operation
* hosting management
* configuration
* networks and devices management
* timetable management
* daemon management and configuration
* cash operations
* customers groups management
* nodes groups management
* customers to groups assignment
* nodes to groups assignment
* voip accounts management
* Userpanel management
* 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. 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.
Before you start check LMS requirements (they're changing). Also if
you're using MySQL check user privileges, they're changed few times in
the past.
Now, 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.
Warning
If you've got CVS version you've to install Smarty library. Just copy
contents of Smarty's /lib directory to /lib/Smarty. It can be done
(including Smarty download) automatic with use of
/devel/smarty_install.sh script.
__________________________________________________________________
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. Calculation of tax value
Below is presented method used by LMS to calculate tax value. Values of
all calculations are rounded to hundredths.
Unitary price in LMS database is brutto value (including tax).
* tax value = (tax rate / 100) + 1
Example: tax rate is 22%
tax value = (22 / 100) + 1 = 1.22
* unitary netto price = unitary brutto price / tax value
Example: unitary brutto price of 1 meter of cable is $2.56, tax
rate is 22%
unitary netto price = $2.56 / 1,22 = $2.10
* total brutto price = unitary brutto price * count
Example: unitary brutto price of 1 meter of cable is $2.56, number
of meters is 1366, tax rate is 22%
total brutto price = $2.56 * 1366 m = $3496.96
* total netto price = total brutto price / tax value
Example: unitary brutto price of 1 meter of cable is $2.56, number
of meters is 1366, tax rate is 22%
total netto price = ($2.56 * 1366 m = $3496.96) / 1,22 = $2866.36
__________________________________________________________________
2.9.2. 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 define division's invoices
data (e.g. header, footer, default expositor, place, bank account) and
configure some options in configuration section [invoices]:
* 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.
When printing by default are displayed original and copy pages, it can
be changed:
* default_printpage
Coma-separated list of default invoice printout pages. You can use
"original", "copy", "duplicate". Default: "original,copy".
Example: default_printpage = "original"
__________________________________________________________________
2.9.2.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.2.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.2.3. Automatic iban account number generation
LMS allows for automatic IBAN number generation. As of now it supports
fixed lenght of 26 digits and 2 letters (letters are set fixed to PL --
POLAND). You need to specify 8 to 20 digits, the rest is taken as
as-many-leading-zeros-as-needed plus Customer-ID Be aware that for
example Cyprus and Hungary also use 26 digits. More on: Wikipedia
__________________________________________________________________
2.9.2.4. 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.3. Transfer forms
Transfer forms it's Polish specific feature. Data for payment form
printouts is get from customer's division info. The title of payment
can be set using 'pay_title' option in [finances] section.
__________________________________________________________________
2.9.4. Cash Receipts
__________________________________________________________________
2.9.4.1. HTML
Receipts are printed in html format by default using provided template.
We chave one printout template for cash-in and cash-out receipts. 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.4.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.5. 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 letters and 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
'plugin' => 'plugin', // plugin file name (in 'name' directory)
'post-action' => 'post-action', // action file executed after document addition (in transaction)
)
?>
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.
Member plugin specify name of php file used for printing additional
fields on document creation form. Plugin can also consist errors
handlers for those fields. After document creation will be executed PHP
script which name (without extension) should be specified in
post-action value.
__________________________________________________________________
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. Notices
In this module, you're able to write administrative notice (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. Reports
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. Notices
You can write administration notice (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 notice and don't
select any of 'Enable/Disable' boxes.
__________________________________________________________________
3.4.5. Reports
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. Search
You can search for devices here by any given criteria. You can enter
whole IP, MAC or device name, or just its fragment and search will
guess for you.
__________________________________________________________________
3.5.4. 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, "gd" for graphic
images or "openlayers" if you want to use map based on this library. 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 pool with
parameters such as domain, DNSes, default gateway and DHCP pool. If you
use LMS to manage numerous networks or you use numerous address pools,
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
pool, defined by its IP address and netmask. All other data is
optional.
Physical interfaces, IP aliases and vlans are recognized in below
manner:
* Physical interface - example: eth0
* IP alias - example: eth0:1
* Vlan interface with VID 19 - example: eth0.19
* First IP alias on vlan interface with VID 19 - example: eth0.19:1
__________________________________________________________________
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 information 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. Debit Notes List
List of debit notes that has been already written out. You're able to
print (by selecting 'Print' icon) and check as accounted selected
notes.
__________________________________________________________________
3.7.10. New Debit Note
Allows you to issue an debit note for selected customer manually.
__________________________________________________________________
3.7.11. Cash Registry
Cash register can be divided on many registries like cash1, cash2, main
cash, bank, etc. On regirstries list are placed all information about
defined registries with actual balance and summary which include only
registries with not set "Disable summary" option.
Each registry can have own numbering of cash-in and cash-out documents
and access rights for users. "Write" privilage is assigned for common
cashiers and dismiss receipts read and addition. "Advanced" users can
edit and delete documents and change number or date when create new
document.
Cash receipts are a proofs of payment in and out cash. Receipts list,
which you'll find by clicking on selected registry on registries 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.12. New Cash Receipt
To create new cash document in first place you must specify registry
and operation type (pay in/pay out), select customer from list or
search them using filter. You can select other operation type i.e.
assets move or operation not associated with customer. Also you can set
date and number (better to leave values proposed by system). Then click
'Select' to affirm your choice. After that you can add any number of
positions with value and description or select them from list of not
closed invoices/credit notes. 'Save and Print' will finish and save
receipt and payments in system and display receipt's printout in new
window.
Printouts look configuration is desribed in chapter Installation and
Configuration.
__________________________________________________________________
3.7.13. 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/2004ID:0013
15.02.2004 Pain Joseph 123,45 Invoice paid - LMS/34/2004
While import operations are being accepted it's possible to enable
auto-accounting of invoices. To do this enable option
'cashimport_checkinvoices' in section [finances]. Invoice (and assigned
credit notes) is checked when imported payment (taking customer balance
into account) is greater than invoice liability.
__________________________________________________________________
3.7.14. Export
Financial data export to external systems rely on generation of text
files with data fetched according to defined filters. For each document
is created one record in text file. Record's format sets user using
variables.
Export configuration is placed in file, which localization is set in
export_config option of section [phpui]. Example values with variables
description you can find in modules/exportcfg.php. The bast way is to
copy that file and there making needed changes.
For each position of Sale Registry (each invoice) we have one record in
result file. When exporting Cash Report one record is for each position
of cash document.
__________________________________________________________________
3.7.15. Reports
There are several options for balance sheet printouts:
* Balance sheet for your network including financial operations for
given period
* Customer balance sheet for given period.
* Sale Registry, which consists of invoices for given period.
* Cash Report, which consists of cash receipts for given period
and/or given registry and cashier.
* Invoices for given period or/and selected customer.
* Transfer forms for selected customer or customers group and given
balance limit (only for polish forms).
* Total invoiceless income for given period
* Liability report for given day, for all or selected user
* Cash import history for given period.
__________________________________________________________________
3.8. Documents
Non-financial documents can be found direct on customer's page or in
'Documents' menu. In LMS you can store prepared files in many formats
or generate new ones with user-defined templates. This feature is most
interesting because makes possible to create expanded plugins. Plugins
can provide many actions not limited to just printout generation.
__________________________________________________________________
3.8.1. List
List consist basic infos about all documents i.e. number, title type,
creation date, obligation dates and customer name. Simple filter let
you documents searching by type and/or customer.
__________________________________________________________________
3.8.2. New document
Documents can be created with templates made accordingly to rules
described in section Other documents. Those can be also prepared files,
which will be uploaded to server. Each document should have defined
title and type. Additionally you might define it's time span (time
until when it's valid) and description. Documents can be numbered with
any numbering plan defined in system.
__________________________________________________________________
3.8.3. Documents Generator
Generator provides possibility to create documents according to
selected template group of customers. With option 'Print' you can print
generated documents but only if they are of html type.
Note
For performance reasons is recommended to use templates optimized for
generator and to not print many (hundreds) documents (possible browser
hang).
__________________________________________________________________
3.8.4. Access Rights
Here you can define users access for specified actions (read, create,
write, confirm, edit, delete) on documents by their types.
__________________________________________________________________
3.9. Hosting
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 five types of accounts now: shell (1), email (2), www
(4), ftp (8) and sql (16). 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.9.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.9.2. New Account
To create new account you have to provide its login, password, choose
domain, at least one account type and assign customer to it.
You can define any home directory for account. Option homedir_prefix
from section [phpui] consists default prefix "/home/".
__________________________________________________________________
3.9.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 physical existing account(s). 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.
__________________________________________________________________
3.9.4. New Alias
Creating alias you have to define login, domain and destination
account(s). Destination accounts must exists in LMS. If you need alias
for external account, you should create an account with redirect
address.
__________________________________________________________________
3.9.5. Domains
Currently LMS can directly manage PowerDNS server with mysql/pqsql
backend. LMS now has full support for most of the features of PowerDNS
server. It has full support for zone types: master, native and slave.
You're able to see basic information about domains on the list such as:
name, type, owner. It's possible to sort this list by any highlighted
column name and to filter list for given criteria and by first letter
of domain name. You can edit domain data by clicking 'Edit' icon. Add
new domain at the bottom and at the top of the list.
__________________________________________________________________
3.9.6. New Domain
Domain data consists of name, description, type (master,slave,native),
IP address of webserver, IP address of mailserver, IP address of master
NS (when type slave is selected) and other parameter which have default
values stored in "zones" section. Domain can be assigned to customer.
__________________________________________________________________
3.9.7. Search
You can search for accounts, aliases and domains here by any given
criteria.
__________________________________________________________________
3.9.8. 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(EPOCH FROM 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 p.password FROM passwd p, domains d WHERE p.domainid = d.id
# AND p.login='%u' AND d.name ='%r' AND p.type & 2 = 2
# AND (p.expdate = 0 OR p.expdate > UNIX_TIMESTAMP())
sql_select: SELECT p.password FROM passwd p, domains d WHERE p.domainid = d.id
AND p.login='%u' AND d.name ='%r' AND p.type & 2 = 2
AND (p.expdate = 0 OR p.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 p.login, \
# p.password, '', 104, 104, '/var/spool/mail/virtual', \
# CONCAT(d.name,'/', p.login, '/'), '', p.login, '' \
# FROM passwd p, domains d WHERE p.domainid = d.id \
# AND p.login = '$(local_part)' AND d.name = '$(domain)' \
# AND p.type & 2 = 2 AND (p.expdate = 0 OR p.expdate > UNIX_TIMESTAMP())
PGSQL_SELECT_CLAUSE SELECT p.login, \
p.password, '', 104, 104, '/var/spool/mail/virtual', \
d.name || '/' || p.login ||'/', '', p.login, '' \
FROM passwd p, domains d WHERE p.domainid = d.id
AND p.login = '$(local_part)' AND d.name = '$(domain)' \
AND p.type & 2 = 2 \
AND (p.expdate = 0 OR p.expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)))
# main.cf (Postfix):
virtual_mailbox_base = /var/spool/mail/virtual
virtual_mailbox_domains = pgsql:/etc/postfix/virtual_domains_maps.cf
virtual_mailbox_maps = pgsql:/etc/postfix/virtual_mailbox_maps.cf
virtual_alias_maps = pgsql:/etc/postfix/virtual_alias_maps.cf
recipient_bcc_maps = pgsql:/etc/postfix/recipient_bcc_maps.cf
# virtual_domains_maps.cf (Postfix):
user = lms
password = dbpass
hosts = localhost
dbname = lms
query = SELECT name FROM domains WHERE name = '%s'
# virtual_mailbox_maps.cf (Postfix):
user = lms
password = dbpass
hosts = localhost
dbname = lms
# MySQL
#query = SELECT CONCAT(d.name, '/', p.login, '/')
# FROM passwd p, domains d WHERE p.domainid = d.id
# AND p.login = '%u' AND d.name = '%d'
# AND p.type & 2 = 2
# AND (p.expdate = 0 OR p.expdate > UNIX_TIMESTAMP())
# PostgreSQL
query = SELECT d.name || '/' || p.login || '/'
FROM passwd p, domains d WHERE p.domainid = d.id
AND p.login = '%u' AND d.name = '%d'
AND p.type & 2 = 2
AND (p.expdate = 0 OR p.expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)))
# virtual_alias_maps.cf (Postfix):
user = lms
password = dbpass
hosts = localhost
dbname = lms
# MySQL
# MySQL
#query = SELECT p.mail_forward
# FROM passwd p
# JOIN domains d ON (p.domainid = d.id)
# WHERE p.login = '%u' AND d.name = '%d'
# AND p.type & 2 = 2 AND p.mail_forward != ''
# AND (p.expdate = 0 OR p.expdate > UNIX_TIMESTAMP())
# UNION
# SELECT CASE WHEN aa.mail_forward != '' THEN aa.mail_forward ELSE CONCAT(p.login, '@', pd.name) END
# FROM aliases a
# JOIN domains ad ON (a.domainid = ad.id)
# JOIN aliasassignments aa ON (aa.aliasid = a.id)
# LEFT JOIN passwd p ON (aa.accountid = p.id AND (p.expdate = 0 OR p.expdate > UNIX_TIMESTAMP()))
# LEFT JOIN domains pd ON (p.domainid = pd.id)
# WHERE a.login = '%u' AND ad.name = '%d'
# AND (aa.mail_forward != '' OR p.id IS NOT NULL)
# PostgreSQL
query = SELECT p.mail_forward
FROM passwd p
JOIN domains d ON (p.domainid = d.id)
WHERE p.login = '%u' AND d.name = '%d'
AND p.type & 2 = 2 AND p.mail_forward != ''
AND (p.expdate = 0 OR p.expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)))
UNION
SELECT CASE WHEN aa.mail_forward != '' THEN aa.mail_forward ELSE p.login || '@' || pd.name END
FROM aliases a
JOIN domains ad ON (a.domainid = ad.id)
JOIN aliasassignments aa ON (aa.aliasid = a.id)
LEFT JOIN passwd p ON (aa.accountid = p.id
AND (p.expdate = 0 OR p.expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0))))
LEFT JOIN domains pd ON (p.domainid = pd.id)
WHERE a.login = '%u' AND ad.name = '%d'
AND (aa.mail_forward != '' OR p.id IS NOT NULL)
# recipient_bcc_maps.cf (Postfix):
user = lms
password = dbpass
hosts = localhost
dbname = lms
# MySQL
#query = SELECT p.mail_bcc
# FROM passwd p, domains d WHERE p.domainid = d.id
# AND p.login = '%u' AND d.name = '%d'
# AND p.type & 2 = 2
# AND p.mail_bcc != ''
# AND (p.expdate = 0 OR p.expdate > UNIX_TIMESTAMP())
# PostgreSQL
query = SELECT p.mail_bcc
FROM passwd p, domains d WHERE p.domainid = d.id
AND p.login = '%u' AND d.name = '%d'
AND p.type & 2 = 2
AND p.mail_bcc != ''
AND (p.expdate = 0 OR p.expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)))
__________________________________________________________________
3.10. Messages
Messages is a component where you can spam groups of your customers
with email or sms messages.
__________________________________________________________________
3.10.1. List
On the list you have a history of sent messages. You can sort them
using filter. Clicking on the message record moves you to information
page with message content and list of recipients. On the list you have
delivery status of every (sub)message.
__________________________________________________________________
3.10.2. New message
To send a message you should specify appropriate group of recipients,
type of message (email/sms). Your attendance can be grouped by status,
network or customer/node groups, etc.
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
%bankaccount - bank account number
__________________________________________________________________
3.10.3. Configuration
Your server has to support PEAR::Mail for this to send email messages.
If you use mail server on remote host, you will need to set options
smtp_host, smtp_port, smtp_username, smtp_password in [mail] section.
Here we've got the list of configuration options for mailing. These
options should be placed in [mail] section.
* debug_email
E-mail address for debugging - messages sent from module 'Messages'
will be delivered to this address instead of sending them to real
users.
Example: debug_email = root@localhost
* 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
SMS configuration is more complex. Forst of all you have to define a
service type to use. This could be a SMS gateway or some software
installed on LMS server (e.g. gnokii, smstools). For SMS configuration
options [sms] section is intended:
* service
service type for sending text messages. Supported values:
'smstools' and 'smscenter'.
Example: service = smstools
* prefix
Phone country code. Default: 48 (Poland)
Example: prefix = 49
* from
Message sender. Default empty.
Example: from = ISP Co.
* username
Username for sms gateway. Default: empty.
Example: username = isp
* password
Password for sms gateway. Default: empty.
Example: password = haslo
* smscenter_type
Type of account you have at smscenter service. LMS will add sender
at the end of message, when static type has been set. Correct
values are: static and dynamic. Default: dynamic.
Example: smscenter_type = static
* smstools_outdir
Directory with outgoing message files for smsd (smstools). HTTP
server must have a write access to it. Deafault:
/var/spool/sms/outgoing.
Example: smstools_outdir = /home/smsd/outgoing
__________________________________________________________________
3.11. 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.12. 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.12.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.12.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 (low): 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 (medium): data older than month will be
approximated to one day.
* High precision (high): data older than month will be approximated
to one hour.
Warning
Data approximation is irreversible.
It's possible to do database compacting with cron. Compacting page can
be viewed (executed) directly by web browser in following way:
links -dump \
"http://lms/?m=trafficdbcompact&level=low&removeold=1&removedeleted=1&loginform[login]=login&loginform[pwd]=pass&override=1"
__________________________________________________________________
3.12.3. Reports
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.13. 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.13.1. Queues List
Basic information 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.13.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.13.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.13.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.5. Reports
Here you can print requests list and helpdesk statistics:
* List of requests with queue, status, uptime and customer filters,
* Requests stats with queue filter
__________________________________________________________________
3.14. 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.14.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.14.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.14.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.15. Configuration
3.15.1. User Interface
3.15.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.15.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 pools 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!
* default_module
Start-up module (filename from /modules without .php). Default:
welcome.
Example: default_module = copyrights
* 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
* divisionlist_pagelimit
Limit of records that can be displayed on one page of divisions
list. Default: 100
Example: divisionlist_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
* 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. Default: 0
(off).
Example: use_current_payday = 1
* default_monthly_payday
Forces to use given day of month as a payment day. Default: 0
(undefined).
Example: default_monthly_payday = 1
* use_invoices
Makes option "with invoice" checked by default. Default: false.
Example: use_invoices = true
* 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
* helpdesk_stats
Adds requests causes stats on ticket view and print pages. Default:
enabled.
Example: helpdesk_stats = true
* helpdesk_customerinfo
Adds customer basic information on ticket view and in
notifications. Default: enabled.
Example: helpdesk_customerinfo = false
* ticketlist_status
Default status filter setting on tickets list. For allowed values
see html source code. Default: not set.
Example: ticketlist_status = -1
* ticket_template_file
Helpdesk ticket printout template file. Default:
rtticketprint.html.
Example: ticket_template_file = ../mytemplates/ticket.html
* to_words_short_version
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_version = 1
* nodepassword_length
Length of (auto-generated) node password. Max.32. Default: 16.
Example: nodepassword_length = 8
* 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
* big_networks
Support for big ISPs e.g. hidding long selection dropdowns.
Default: false.
Example: big_networks = true
* short_pagescroller
Enables page scroller designed for lists with very big number of
pages. Default: false.
Example: short_pagescroller = true
* ewx_support
Support for EtherWerX devices. Default: false.
Example: ewx_support = true
* default_assignment_period
Default period value for assignment. Possible values: disposable -
0 daily - 1 weekly - 2 monthly - 3 quarterly - 4 yearly - 5
Default: 0
Example: default_assignment_period = 3
__________________________________________________________________
3.15.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.15.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
* %I - additional part of number (works with cash documents only)
* %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.15.4. Divisions
Divisions/Companies are used for customers grouping. You should create
at least one division. You can define division's short and long names,
address bank account (or mass-payments account prefix) and other data
for invoices. Locked division cannot be assigned to customer.
__________________________________________________________________
3.15.5. 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.15.6. Daemon
When you create hosts list, you will be able to configure daemon lmsd.
Daemon configuration is described in appropriate chapter.
__________________________________________________________________
3.15.7. Import sources
It's possible to import customer payments from many sources (banks).
Here you can define its names/description. Then you will able to select
source from the list to add/import payments or some create payments
reports.
__________________________________________________________________
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 about debt, new
invoice, etc.
lms-notify-sms SMS Notifications about customers deb, new invoice, etc.
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 it's a 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. For SMTP connection
Mail::Sender module is used.
__________________________________________________________________
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
* %cid - customer ID
* %number - document number (invoices, debit notes and deadline
notifies only)
* %value - invoice value (invoices and deadline notifies only)
* %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 (also in lms-notify-sms):
* debtors_template
Lets you setup message template which will be sent to debted
customers. Default: none.
Example: debtors_template = /etc/lms/debtors_template.txt
* debtors_subject
Lets you set subject of message to debtors. Default: 'Debtors
notification'.
Example: debtors_subject = Debt information
* invoices_template
The message template which will be sent to customers if new invoice
is created (in last 24 hours). Default: none.
Example: invoices_template = /etc/lms/invoices_template.txt
* invoices_subject
Subject of 'invoices' message. Default: 'New invoice notification'.
Example: invoices_subject = Invoice information
* notes_template
The message template which will be sent to customers if new debit
note is created (in last 24 hours). Default: none.
Example: notes_template = /etc/lms/notes_template.txt
* notes_subject
Subject of 'notes' message. Default: 'New debit note notification'.
Example: notes_subject = Debit note information
* deadline_template
Lets you setup message template which will be sent to debted
customers when (not payed) invoice reaches paytime. Default: none.
Example: deadline_template = /etc/lms/deadline_template.txt
* deadline_subject
Subject of 'deadline' message. Default: 'Invoice deadline
notification'.
Example: deadline_subject = Deadline information
* limit
Lets you setup limit of customer debt. The message will be sent if
customer balance is below that value. Default: limit = 0
Example: limit = -20
And list of options for mailing only:
* mailfrom (mandatory)
Lets you setup email of the sender. Default: none.
Example: mailfrom = staff@bigpro.com
* mailfname
Sender name. Default: none
Example: mailfname = Administrators
* smtp_host
SMTP server to be used when sending emails. Default: localhost
Example: smtp_host = smtp.bigpro.com
* smtp_auth
SMTP authorization type. Allowed values: LOGIN, PLAIN, CRAM-MD5,
NTLM. Default: none
Example: smtp_auth = LOGIN
* smtp_user
Login for SMTP authorization. Default: none
Example: smtp_user = admin
* smtp_pass
Password for SMTP authorization. Default: none
Example: smtp_pass = password
* 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 it's a lms-notify equivalent, but it's intended to send
reminders via SMS. Actually it supports smstools and gnokii services.
Use [sms] section for SMS Service configuration.
Configuration of lms-notify-sms should be set in lms.ini file,
[notify-sms] section. Here you can use all lms-notify options plus:
* service
Allows you to overwrite SMS service option from [sms] section.
Default: empty
Example: service = smstools
__________________________________________________________________
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
- it will be replaced by current date, and %b and %B like in
lms-notify script. 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)
Payment type identifier (1-cash, 2-transfer, 3-transfer/cash,
4-card, 5-compensation, 6-barter, 7-contract). Default: 2
Example: paytype = 1
* suspension_description (optional)
Suspension description for suspended liabilities added at the end
of comment. Default: ''
Example: suspension_description = '(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 format)
%current_month - period form 1st day of current month to the last
day
%current_period - current month in MM/YYYY format
%next_period - next month in MM/YYYY format
%prev_period - previous month in MM/YYYY format
%desc - tariff description
Example: comment = 'Subscription for %current_month'
* settlement_comment (optional)
Description of settlement.
Default set to comment option contents.
Example: settlement_comment = 'Settlement for %period'
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
* 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
__________________________________________________________________
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
Don't put 'ddns-update-style none;' at the 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
* authoritative
Add 'authoritative;' entry at the beginning of file. Default: Off.
Example: authoritative = 1
* 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, [ether]
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:
LWP::UserAgent, MIME::QuotedPrint and Mail::Sender.
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 = ''
* customergroups
List of (space separated) customer groups, that should be
considered while sending invoices. Default: unset - all customers.
Example: customergroups = group1 group2
* smtp_host
SMTP server to be used when sending emails. Default: localhost
Example: smtp_host = smtp.bigpro.com
* smtp_auth
SMTP authorization type. Allowed values: LOGIN, PLAIN, CRAM-MD5,
NTLM. Default: none
Example: smtp_auth = LOGIN
* smtp_user
Login for SMTP authorization. Default: none
Example: smtp_user = admin
* smtp_pass
Password for SMTP authorization. Default: none
Example: smtp_pass = password
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 Mail::Sender 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_host
SMTP server to be used when sending emails. Default: localhost
Example: smtp_host = smtp.bigpro.com
* smtp_auth
SMTP authorization type. Allowed values: LOGIN, PLAIN, CRAM-MD5,
NTLM. Default: none
Example: smtp_auth = LOGIN
* smtp_user
Login for SMTP authorization. Default: none
Example: smtp_user = admin
* smtp_pass
Password for SMTP authorization. Default: none
Example: smtp_pass = password
* 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/
* include_customerinfo
Adds basic customer information in new ticket notification
footnote. Default: On.
Example: include_customerinfo = 0
__________________________________________________________________
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.
* customergroups
>List of (space separated) groups of customers, that should be
considered while creating configuration file. If unset,
configuration will include all groups.
Example: customergroups = group1 group2
* excluded_customergroups
>List of (space separated) groups of customers, that should be
ommited while creating configuration file.
Example: excluded_customergroups = group3 group4
* 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
* excluded_networks
>List of (space separated) networks, that should be ommited while
creating configuration file.
Example: excluded_networks = cust4-publ cust5-publ
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 pools).
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 pools).
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 pools).
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 pools).
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 pools).
Example: dhcpnode_priv = node unknown (%IP) reject;
* dhcpnode_publ
Adds line for each IP address within DHCP dynamic range (parsed
only for public address pools).
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 pools).
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 pools).
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 pools)
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 pools)
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
* %CMAC - MAC address in CISCO format (FFFF.FFFF.FFFF)
* %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
* %PORT - device's port, to which node is connected
* %UPRATE - guaranteed upload rate
* %NUPRATE - guaranteed upload rate (for night hours)
* %DOWNRATE - guaranteed download rate
* %NDOWNRATE - guaranteed download rate (for night hours)
* %UPCEIL - maximum upload rate
* %NUPCEIL - maximum upload rate (for night hours)
* %DOWNCEIL - maximum download rate
* %NDOWNCEIL - maximum download rate (for night hours)
* %CLIMIT - limit of concurrent connections
* %NCLIMIT - limit of concurrent connections (for night hours)
* %PLIMIT - maximum number of packets per second
* %NPLIMIT - maximum number of packets per second (for night hours)
* %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)
--lmsbindir=DIR sets location of target LMS binaries (PREFIX/lms/bin)
--lmslibdir=DIR sets location of target LMS modules (PREFIX/lms/lib)
--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 Configuration -> Daemon 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 mustcorrespond to the
one specified in hosts configuration in UI
--pidfile -P pid_file pidfile where daemon write pid (default: none)
--ssl -s use SSL connection (default: disabled)
--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.
Spaces in instance name should be replaced by '\s' sequence, i.e. lmsd
-i "my\sinstance".
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', '%tariff'
by name of liability, %month by full name of current month and
%year by current year, %next_mon by next month in YYYY/MM format.
Default: 'Subscription: '%tariff' for period: %period'.
Example: comment = 'Subscription %tariff'
* settlement_comment
Description of settlement operation. '%period' will be replaced by
start and end date of settlement period, e.g. '2003/10/20 -
2003/11/09', and '%tariff' by name of liability. Defaults to
comment option.
Example: settlement_comment = 'Settlement of 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 identifier (1-cash, 2-transfer, 3-transfer/cash,
4-card, 5-compensation, 6-barter, 7-contract). Default: 2
(transfer).
Example: paytype = 1
* numberplan
ID of invoices numbering plan defined in Configuration -> Numbering
Plans. Default: 0 (default plan).
Example: numberplan = 1
* check_invoices
Enables checking of invoices as accounted for customers with
balance equal or greater than zero. Default: false.
Example: check_invoices = 1
* networks
List of network names to restrinct customers for accounting.
Default: empty (all networks).
Example: networks = "lan1 lan2"
* excluded_networks
List of excluded network names to restrinct customers for
accounting. Default: empty (none).
Example: excluded_networks = "lan3 lan4"
* customergroups
List of customers groups to restrict customers for accounting.
Default: empty (all groups).
Example: customergroups = "group1 group2"
* excluded_customergroups
List of excluded customers groups to restrict customers for
accounting. Default: empty (none).
Example: excluded_customergroups = "group3 group4"
__________________________________________________________________
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. Also,
disables computers due to assignments expiration. 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 limit as numeric value or as percentage of sum of
customer's monthly assignments (with '%' sign). 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.
You can also use %B for real customer balance and %b for unsigned
balance value. Default: 'Blocked automatically due to payment
deadline override at %time".
Example: warning = ""
* expired_warning
Sets the message to customer when disabling his computers access
due to all assignments expiration. If empty, warning will be not
set. Date in message is substituted providing '%time' variable.
Default: 'Blocked automatically due to tariff(s) expiration at
%time'.
Example: expired_warning = ""
* warnings_only
Here you can to decide, if you want to use this module only for
warnings or to actually cut people off. Works for customers with
assignments. Default: false.
Example: warnings_only = true
* setnodegroup_only
Sets nodes group name. Module assigns to that group all computers
of customer who exceeds value or invoice limit. Customer's status
isn't changed. Default: none.
Example: setnodegroup_only = blocked_nodes
* disable_suspended
Use this option to disable customers with suspended all current
assignments. Default: false.
Example: disable_suspended = true
* use_nodeassignments
You should enable this option only if you are using nodes with
tariffs assignments. In other way tariffs assignments with
customers are checked. Default: false.
Example: use_nodeassignments = true
* use_customerassignments
You should disable this option only if you don't want to check
assignments (or node assignments are used). Default: true.
Example: use_customerassignments = false
* check_invoices
This option enables additional checking if customer has unpayed
invoices with deadline date older than date specified in 'deadline'
option. Default: false.
Example: check_invoices = true
* deadline
Sets period in days (from invoice deadline date), after which
unpayed invoice is considered for 'check_invoices' check. By
default, customer would be blocked just after deadline. Default: 0.
Example: deadline = 30
* customergroups
List of customers groups to restrict customers for accounting.
Default: empty (all groups).
Example: customergroups = "group1 group2"
* excluded_customergroups
List of excluded customers groups to restrict customers for
accounting. Default: empty (none).
Example: excluded_customergroups = "group3 group4"
* networks
List of network names to get into consideration. Default: empty
(all networks).
Example: networks = 'lan1 lan2'
* excluded_networks
List of network names to exclude. Default: empty (none).
Example: excluded_networks = 'lan3 lan4'
__________________________________________________________________
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, %b - broadcast address.
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
(nodes and network devices addresses) from database fetching their
connection and warnings status, private and public addresses, network
that they are connected to and groups of they owners. Because of that
it is possible to create any set of firewall rules, or /etc/hosts file.
Data is written to file and after that specified shell command can be
executed.
__________________________________________________________________
6.2.8.2. Configuration
The following replacement variables can be used in host rule options:
%i - IP address,
%ipub - public IP address,
%id - node ID,
%m - MAC address,
%ms - comma-separated list of node MACs
%n - host name,
%p - node (computer) password,
%port - device's port to which computer is connected,
%l - host location,
%devl - location of device to which node is connected,
%info - node description,
%domain - domain,
%net - network name,
%gw - gateway address of network,
%if - network's interface,
%mask - network mask,
%addr - network's address,
%prefix - network mask CIDR-style prefix,
%dns, %dns2 - DNS server addresses,
%dhcps, %dhcpe - start and end of DHCP range,
%wins - WINS server address,
%i16 - IP's last octet in hex,
%i16pub - public IP's last octet in hex.
%domainpub - domain name of public network,
%netpub - public network name,
%gwpub - gateway address of public network,
%ifpub - public network's interface,
%maskpub - public network mask,
%addrpub - public network's address,
%prefixpub - public network mask CIDR-style prefix,
%dnspub, %dns2pub - DNS server addresses in public network,
%dhcpspub, %dhcpepub - start and end of DHCP range in public network,
%winspub - WINS server address in public network,
%customer - node owner's name,
%cid - node owner's ID,
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"
* host_begin
Host rule header. Default: ""
Example: host_begin = "#%n\n"
* host_end
Host rule footer. Default: ""
Example: host_end = "\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 = ""
* warnedhost
Line with rule(s) for node with set warnings flag.
Example: warnedhost = "$IPT -A PREROUTING -s %i --dport 80 -p tcp
-j REDIRECT --to-port 82\n"
* public_warnedhost
Line with rule(s) for node with set warnings flag and specified
public IP. By default rule specified in 'warnedhost' option.
Example: public_warnedhost = ""
* public_replace
Specify that rules for public addresses would overwrite main rules
or be added to them. Default: enabled.
Przyk³ad: public_replace = false
* warn_replace
Specify that rules for nodes with warnings would replace main rules
or be added to them. Default: disabled.
Przyk³ad: warn_replace = true
* 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 groups names which members should be included in
config (case insensitive). Default: empty (all groups).
Example: customergroups = "group1 group2"
* nodegroups
List of node groups names which members should be included in
config (case insensitive). Default: empty (all groups).
Example: nodegroups = "group1 group2"
* excluded_networks
List of network names which members should be excluded from config
(case insensitive). Default: empty (none).
Example: excluded_networks = "lan3 lan4"
* excluded_customergroups
List of customer groups names which members should be excluded from
config (case insensitive). Default: empty (none).
Example: excluded_customergroups = "group1 group2"
* excluded_nodegroups
List of node groups names which members should be excluded from
config (case insensitive). Default: empty (none).
Example: excluded_nodegroups = "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
* skip_host_ips
If enabled (yes, true) hosts IPs (customers nodes) will be ignored
(omitted). Default: no
Example: skip_host_ips = yes
* multi_mac
If enabled (yes, true) each IP-MAC pair will be listed. Default: no
Example: multi_mac = yes
__________________________________________________________________
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 information (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, %if - network interface, %uprate, %downrate,
%upceil, %downceil, %plimit, %climit, %o1, %o2, %o3, %o4 - IP's octets,
%h1, %h2, %h3, %h4 - IP's octets in hex and %x - integer counter with
initial value of 100 incremented by one for each node (or customer).
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 99000kbitquantum 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 98500kbitprio 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_up
Mark rule for each computer. Default:
# %n
$IPT -t mangle -A LIMITS -s %i -j MARK --set-mark %x
Example: host_mark_up = ""
* host_mark_down
Mark rule for each offline computer. Default:
$IPT -t mangle -A LIMITS -d %i -j MARK --set-mark %x
Example: host_mark_down = ""
* 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/%c";
\nnotify yes; \n}; \n'.
Example: conf-revers-entry = 'zone "%c.in-addr.arpa" { \n\ttype
master; \n\tfile "reverse/%c"; \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. Supports formating sequences like in C
language (\t, \n, \\).
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 ")
* len(string)
String length (strlen() in C).
Przyk³ad: length = len(string)
* 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)}
__________________________________________________________________
6.3.3.8. Constants
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
ten - tax exempt number
ssn - security serial number
regon - business registration number
icn - identity card number
rbe - register of business entities number
info - additional information
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 information
message - warning message contents
mac - MAC address
passwd - password
ip - IP address
ip_pub - public IP address
linktype - connection type (0-cable, 1-air)
port - device's port to which node is connected
chkmac - MAC checking (0-disabled, 1-enable)
halfduplex - duplex mode (0-full, 1-half)
* 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 ip from 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 OR cash.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
phone - user's phone number
position - user's position name
rights - binary access rights
hosts - list of hosts allowed to login
passwd - password to login
ntype - supported notofication types
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)
access - whether the account is active (0/1)
accessfrom - date from which the account is active
accessto - date to which the account is active
__________________________________________________________________
7.2.2. Customers ('customers')
id - serial number
lastname - last/company name
name - first name
divisionid - identifier of company/division
status - customer status (3-connected, 2-awaiting, 1-prospect)
type - legal personality (0-private person, 1-legal entity)
email - email address
pin - pin number (for authentication)
address - street address (street, apartment, flat, etc)
zip - zip code
city - location (city)
countryid - country identifier
post_name - correspondence address - name
post_address - correspondence address - street, apartment, flat, etc
post_zip - correspondence address - zip code
post_city - correspondence address - location (city)
post_countryid - correspondence address - country identifier
ten - tax exempt number
ssn - social security number
regon - business registration number
rbe - register of business entities
icn - identity card number
info - additional information
notes - notes
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
cutoffstop - date to which customers cutting off is disabled
paytime - invoices deadline in days
paytype - invoices payment type identifier (see documents table)
einvoice - enables e-invoices
invoicenotice - enables invoices delivery via e-mail
mailingnotice - enables messages delivery via e-mail or sms
__________________________________________________________________
7.2.3. Customer groups ('customergroups')
id - serial number
name - group name
description - group description
__________________________________________________________________
7.2.4. Customer groups - assignments ('customerassignments')
id - serial number
customergroupid - group serial number
customerid - customer serial number
__________________________________________________________________
7.2.5. Customer groups - users access ('excludedgroups')
id - serial number
userid - user serial number
customergroupid - group serial number
__________________________________________________________________
7.2.6. 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
disabled - disabled/enabled flag (1/0)
notes - additional notes
__________________________________________________________________
7.2.7. Network devices ('netdevices')
id - serial number
name - name
location - physical location text
location_city - city identifier
location_street - street identifier
location_house - house number
location_flat - flat number
description - device summary
producer - manufacturer's name
model - model number
serialnumber - products serial number (not DB identifier)
ports - number of connections available
purchasetime - purchase date
guaranteeperiod - period in months (NULL - lifetime)
shortname - shortname (radius)
nastype - NAS type identifier (radius)
clients - max. number of clients (radius)
secret - password (radius)
community - SNMP community
channelid - STM channel identifier (ewx_channels table)
longitude - geog. longitude
latitude - geog latitude
__________________________________________________________________
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)
srcport - begin's port number
dstport - end's port number
__________________________________________________________________
7.2.9. Computers and IP addresses ('nodes')
id - serial number
name - device name
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)
port - port number in device
access - connected/disconnected (cutoff) (1/0)
warning - should be warned with administration message? (1/0)
chkmac - enable/disable MAC checking? (1/0)
halfduplex - half/full duplex mode (0/1)
lastonline - last network activity timestamp
info - additional information
location_address - address string
location_city - city identifier
location_street - street identifier
location_house - house number
location_flat - flat number
nas - NAS flag (1/0)
longitude - geog. longitude
latitude - geog latitude
__________________________________________________________________
7.2.10. MAC addresses ('macs')
id - serial number
mac - MAC address
nodeid - IP address identifier (nodes table)
__________________________________________________________________
7.2.11. Node groups ('nodegroups')
id - serial number
name - group name
prio - group order
description - group description
__________________________________________________________________
7.2.12. Node groups - assignments ('nodegroupassignments')
id - serial number
nodegroupid - group serial number
nodeid - node serial number
__________________________________________________________________
7.2.13. NAS Device Types ('nastypes')
id - serial number
name - type name
__________________________________________________________________
7.2.14. 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
importid - import identifier
sourceid - import source identifier
comment - description of operation
__________________________________________________________________
7.2.15. 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
sourceid - import source identifier
sourcefileid - import file identifier
closed - yes (1), if operation was moved to cash table
__________________________________________________________________
7.2.16. Cash import sources ('cashsources')
id - serial number
name - name
description - additional information
__________________________________________________________________
7.2.17. Cash import packages ('sourcefiles')
id - serial number
name - filename
idate - date/time of import
userid - user identifier
__________________________________________________________________
7.2.18. Subscription fees ('tariffs')
id - serial number
name - subscription name
type - subscription type (see lib/definitions.php)
value - amount
taxid - tax rate identifier
period - payment period (for specified tariff value)
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
uprate_n - upload warranty at night
upceil_n - upload boundary at night
downrate_n - download warranty at night
downceil_n - download boundary at night
climit_n - limit of concurrent connections at night
plimit_n - limit of packets per second at night
dlimit - limit of data per time unit
domain_limit - limit of domains
alias_limit - limit of aliases
sh_limit - limit of shell accounts
mail_limit - limit of mail accounts
www_limit - limit of www accounts
ftp_limit - limit of ftp_accounts
sql_limit - limit of sql accounts
quota_sh_limit - quota limit of shell account
quota_mail_limit - quota limit of mail account
quota_wwww_limit - quota limit of www account
quota_ftp_limit - quota limit of ftp account
quota_sql_limit - quota limit of sql account
description - description for subscription
disabled - disabled/enabled flag (1/0)
__________________________________________________________________
7.2.19. Promotions ('promotions')
id - serial number
name - promotion name
description - additional information
disabled - status
__________________________________________________________________
7.2.20. Promotion Schemas ('promotionschemas')
id - serial number
name - schema name
description - additional information
promotionid - promotion identifier
data - schema periods definition
disabled - status
continuation - contract continuation option
ctariffid - additional continuation tariff identifier
__________________________________________________________________
7.2.21. Schema-To-Tariff assignments ('promotionassignments')
id - serial number
promotionschemaid - schema identifier
tariffid - subscription identifier
data - schema values definition
__________________________________________________________________
7.2.22. Custom liabilities ('liabilities')
id - serial number
name - liability name/description
value - amount
taxid - tax rate identifier
prodid - product/service classification number
__________________________________________________________________
7.2.23. 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.24. 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)
pdiscount - discount percentage
vdiscount - discount value
suspended - is this payment suspended? (1 - yes, 0 - no)
settlement - do deficient period settlement? (1 - yes, 0 - no)
paytype - invoice payment type identifier
numberplanid - numbering plan identifier
__________________________________________________________________
7.2.25. Nodes-tariffs assignments ('nodeassignments')
id - serial number
assignmentid - financial assignment serial number
nodeid - node serial number
__________________________________________________________________
7.2.26. 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.27. 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.28. Numbering plans to divisions assignments ('numberplanassignments')
id - serial number
planid - numbering plan identifier
divisionid - division identifier
__________________________________________________________________
7.2.29. Cash registries ('cashregs')
id - serial number
name - registry name
description - additional description
in_numberplanid - numbering plan identifier for cash-in receipts
out_numberplanid - numbering plan identifier for cash-out receipts
disabled - summary disabling (0/1)
__________________________________________________________________
7.2.30. Cash registries - access rights ('cashrights')
id - serial number
regid - registry serial number
userid - user serial number
rights - (1-read, 2-write, 3-advanced)
__________________________________________________________________
7.2.31. Cash registries - cash history ('cashreglog')
id - serial number
regid - registry serial number
userid - user serial number
time - entry timestamp
value - real cash state value
snapshot - cash state value
description - additional information
__________________________________________________________________
7.2.32. Documents: invoices, receipts, contracts, etc. ('documents')
id - serial number
number - document number (%N)
extnumber - additional (extended) number part (%I)
numberplanid - numbering plan identifier
type - document type (1 - invoice, 2 - cash receipt)
cdate - date of write out
sdate - sale date (for invoices)
paytime - deadline in days
paytype - payment type (1-cash, 2-transfer, 3-transfer/cash, 4-card,
5-compensation, 6-barter, 7-contract)
customerid - customer (buyer) serial number
userid - user serial number
divisionid - identifier of company/division
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
countryid - country identifier
closed - is document (invoice) closed (accounted)? (0/1)
reference - document ID reference
reason - e.g. invoice note reason
__________________________________________________________________
7.2.33. 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 information
__________________________________________________________________
7.2.34. Invoices ('invoicecontents')
docid - invoice serial number
itemid - invoice item identifier
value - amount
pdiscount - discount percentage
vdiscount - discount value
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.35. Debit notes ('debitnotecontents')
docid - debit note serial number
itemid - debit note item identifier
value - amount
description - description for the note item
__________________________________________________________________
7.2.36. Cash Receipts ('receiptcontents')
docid - receipt serial number
itemid - receipt item identifier
regid - registry serial number
value - amount
description - description for receipt item
__________________________________________________________________
7.2.37. Documents - access rights ('docrights')
userid - user identifier
doctype - document type id (see lib/definitions.php)
rights - (1-read, 2-create, 3-confirm, 4-edit, 5-delete)
__________________________________________________________________
7.2.38. Internet Messengers ('imessengers')
id - serial number
customerid - customer serial number
uid - messenger user name/identifier
type - messenger type (0-gadu-gadu, 1-yahoo, 2-skype)
__________________________________________________________________
7.2.39. Customers contacts ('customer contacts')
id - serial number
customerid - customer serial number
phone - phone number
name - contact name/description
type - contact type (sum of: 1-mobile, 2-fax)
__________________________________________________________________
7.2.40. Domains ('domains')
id - serial number
name - domain name
description - comments
type - DNS type ('MASTER', 'SLAVE', 'NATIVE')
master - master DNS server
account - email address of DNS administrator
last_check - timestamp
notified_serial - timestamp
__________________________________________________________________
7.2.41. DNS Records ('records')
id - serial number
domain_id - domain serial number
name - name
type - record type (MX, SOA, A, AAAA, etc.)
content - data
ttl - TTL
prio - priority
change_date - last change timestamp
__________________________________________________________________
7.2.42. 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
quota_sql - sql database space limits
mail_forward - account for mail forwarding
mail_bcc - account for blind carbon copy mail
description - additional information
__________________________________________________________________
7.2.43. Aliases ('aliases')
id - serial number
login - account name (without domain)
domainid - account serial number
__________________________________________________________________
7.2.44. Alias-to-account assignments ('aliasassignments')
id - serial number
aliasid - alias serial number
accountid - account serial number
mail_forward - forward address
__________________________________________________________________
7.2.45. VoIP Accounts ('voipaccounts')
id - serial number
ownerid - customer identifier
login - login
passwd - password
phone - phone number
access - enabled/disabled (1/0)
creationdate - date of account creation
moddate - date of last account modification
creatorid - creator (user) identifier
modid - last change (user) identifier
__________________________________________________________________
7.2.46. Bandwidth consumption statistics ('stats')
nodeid - node serial number
dt - timestamp
upload - number of bytes sent
download - number of bytes received
__________________________________________________________________
7.2.47. Helpdesk - Request Tracking ('rtqueues')
id - serial number
name - queue name
email - email account for the queue
description - main description for the queue
__________________________________________________________________
7.2.48. 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)
cause - request cause (0-unknown, 1-customer, 2-company)
owner - user serial number (ticket's owner)
creatorid - user serial number (ticket's creator)
createtime - timestamp of report
__________________________________________________________________
7.2.49. 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.50. Helpdesk - Request Tracking - continued... ('rtattachments')
messageid - message serial number
filename - name of file attachment
contenttype - type of file
__________________________________________________________________
7.2.51. Helpdesk - Request Tracking - continued... ('rtnotes')
id - serial number
ticketid - ticket serial number
userid - LMS user serial number
body - content of note
createtime - date of creation
__________________________________________________________________
7.2.52. 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.53. 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.54. 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)
moduserid - id of last user that modified the event
moddate - date of last event modification
__________________________________________________________________
7.2.55. Timetable - assignments ('eventassignments')
eventid - event identifier
userid - user identifier
__________________________________________________________________
7.2.56. Sessions ('sessions')
id - session identifier
ctime - create time
mtime - last modification time
atime - last access time
vdata - verification data
content - data
__________________________________________________________________
7.2.57. Hosts ('hosts')
id - identifier
name - host name
description - additional information
lastreload - last reload date
reload - reload order
__________________________________________________________________
7.2.58. 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 information
disabled - status (enabled/disabled)
__________________________________________________________________
7.2.59. Daemon configuration - options ('daemonconfig')
id - identifier
instanceid - instance identifier
var - option name
value - option value
description - additional information
disabled - status (enabled/disabled)
__________________________________________________________________
7.2.60. States ('states')
id - identifier
name - state name
description - additional information
__________________________________________________________________
7.2.61. Zip codes ('zipcodes')
id - identifier
zip - zip code
stateid - state identifier
__________________________________________________________________
7.2.62. Countries ('countries')
id - identifier
name - country name
__________________________________________________________________
7.2.63. Companies/Divisions ('divisions')
id - identifier
shortname - division short name
name - division long name
address - address
zip - zip code
city - city
countryid - country identifier
ten - tax exempt number
regon - business registration number
account - bank account or mass payments account prefix
description - additional information
status - lock status (1/0)
inv_header - invoice header
inv_footer - invoice footer
inv_author - invoice default author
inv_cplace - invoice creation place
inv_paytime - invoice deadline
inv_paytype - invoice payment type (see documents table)
__________________________________________________________________
7.2.64. Messages - list ('messages')
id - serial number
subject - message subject
body - message contents
cdate - creation date
type - type (1-email, 2-sms)
userid - sender (user) identifier
sender - e-mail 'From' header
__________________________________________________________________
7.2.65. Messages - items ('messageitems')
id - serial number
messageid - message identifier
customerid - customer identifier
destination - destination (phone num./e-mail)
lastdate - last meaning date
status - sending status (see lib/definitions.php)
error - error message
__________________________________________________________________
7.2.66. 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. 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 information 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.
__________________________________________________________________
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):
# version 2.5
redirector_bypass on
redirect_program /path/to/lms-squid
# version 2.6
url_rewrite_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. Userpanel
9.1. About
Userpanel is automated virtual customer service, based on LMS and using
its core features. It enables customers (or it's intended to) to do
review their payments, change their personal details or computer
properties, modify subscriptions, submit problems, track their requests
on Helpdesk and print invoices. It means, it makes a closer contact
with their ISP.
__________________________________________________________________
9.2. Installation
9.2.1. Installation
You should define sys_dir directory in lms.ini file pointing to your
LMS installation dir, as Userpanel will need LMS libraries located
under this directory to run. Additionally you should enter your
Userpanel location in userpanel_dir variable.
__________________________________________________________________
9.2.2. Configuration
Userpanel, besides options available to setup in LMS-UI, uses also
those enclosed in [userpanel] section (also available in lms.ini file).
__________________________________________________________________
9.2.3. Modules
Userpanel modules are located in modules subdirectory. You can turn it
on or off simply by copying module into, or deleting it from this
directory, respectively.
__________________________________________________________________
9.3. Configuration
Userpanel configuration is made simple thanks to special configuration
panel available in Userpanel -> Configuration menu in LMS-UI. LMS
detects Userpanel presence and unhides this menu if userpanel_dir
variable has been set in [directories] section of lms.ini file.
Main window contains global configuration options and list of present
(enabled) modules. Choosing any of this will direct you to
configuration options screen specific to respective module.
__________________________________________________________________
9.4. Graphical themes (styles)
Userpanel interface is designed to allow its easy adoption to your own
needs and to blend into your existing web pages layout. There is no
need to modify templates code to achieve this goal.
All important files, that is css styles definition and images are
located in style directory, each style in separate directory,
corresponding to its name. If any of the files is missing, the one from
the default style will be used instead. Styles directory, besides css,
images and Javascript, contains two simple Smarty templates, one
containing global page layout with main menu and content of chosen
module below (body.html) and one with table layout, used by modules to
draw anything inside the box (box.html).
Each of Userpanel modules can be styled too, as it contains
corresponding style directory within its directory structure. If any of
the file is missing in specific style, the one from main style
directory will be used instead.
__________________________________________________________________
9.5. Modules
Userpanel is built with modularity principle, which means that each
module, which represents one menu entry is contained in separate
subdirectory of modules directory.
__________________________________________________________________
9.5.1. Construction of module
This graph represents directory structure of typical module:
module_name
|---locale
| |---en
| |---strings.php
|---style
| |---default
| |---image.gif
|---templates
| |---template1.html
| |---template2.html
|---upgradedb
| |---mysql.2005081901.php
| |---postgres.2005081901.php
|---configuration.php
|---functions.php
This requires a few words of explanation:
* locale directory contains appropriate locale, obviously. However
strings.php file contains only translation strings used in
containing module,
* style is obviously image and css style dir, with subdirectories for
each style (graphical theme) installed in Userpanel,
* templates contains Smarty templates for given module,
* upgradedb contains auto-upgrade files for tables being used by
module. Table names, for those used exclusively by one module,
should contain up_modulename_ prefix,
* configuration.php and functions.php are two files required for each
module. They are described in detail later in this document.
__________________________________________________________________
9.5.2. Mandatory files
__________________________________________________________________
9.5.2.1. configuration.php
This file contains configuration of given module and is always included
during Userpanel initialization. Usually it's built as follows:
<?php
$USERPANEL->AddModule(trans('Help'), // Name in menu
'help', // Module name (must be identical as module dir)
trans('Runs problems solving creator'), // Tip (on menu hover)
5, // Priority (lower first)
trans('This module shows solving problems creator'), // Description
2005081901, // DB version (similar to LMS, see
// lms/lib/upgradedb.php)
array( // Array of submenus im LMS-UI Userpanel menu
array( // (see lib/LMS.menu.php)
'name' => trans('Submenu'),
'link' => '?m=userpanel&module=help',
'tip' => trans('Tooltip'),
),
)
);
?>
__________________________________________________________________
9.5.2.2. functions.php
This file contains given module functions. There is special function,
named module_main() executed first when module is called. If any
function is intended to be accessible from Userpanel UI, it should be
prefixed with module_, ie. module_function1(), which will be available
from the following URL: http://userpanel/?m=module&f=function1.
Function named module_setup() is being called from configuration panel
of LMS-UI.
__________________________________________________________________
Chapter 10. FAQ
10.1. My network device map does not show up. What to do?
10.2. How to add two computers with the same IP?
10.3. How to add two computers with the same MAC?
10.4. I see following error: Can't locate Config/IniFiles.pm in @INC
...What should I do?
10.5. I make few corrections. Do you accept any patches?
10.6. What is current version of LMS, which one i should use?
10.7. How to unsubscribe from the mailing list?
10.8. Insecure $ENV{BASH_ENV} while running -T switch...
10.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.
10.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.
10.3. How to add two computers with the same MAC?
Check documentation. You probably look for allow_mac_sharing = 1.
10.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'.
10.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 -uN > /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.
10.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: www.lms.org.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.
10.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.lms.org.pl.
10.8. 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.