LMS - LAN Management System 1.10.6 Hank

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. Accounts
3.10. Mailing
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. 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.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 cvs.lms.org.pl, 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

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


1.4.5. Commercial Support

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


Chapter 2. Installation and configuration

2.1. Intro

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

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

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


2.2. Requirements

2.2.1. Web Server

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


2.2.2. PHP Interpreter

Interpreter version should be 4.2.x or higher. PHP can be downloaded from www.php.net. At least following PHP modules needs to be installed (look for "extension" in php.ini or in output of phpinfo function):

  • pcre, posix,

  • zlib (for compressed backups),

  • gd or ming (for network map),

  • mysql or 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.1.x or higher is supported.


2.2.4. Smarty Library

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


2.2.5. Perl

LMS-MGC and the rest of Perl scripts requires also Perl interpreter and some modules:

  • Perl and its basic modules (POSIX, GetOpt::Long),

  • Config::IniFiles,

  • DBI,

  • DBD-mysql (if you use MySQL),

  • DBD-Pg (if you use Postgres),


2.2.6. C Compiler

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


2.2.7. Web Browser

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


2.3. LMS Installation

LMS in tarball (.tar.gz) archive can be downloaded from project home page (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;
mysql> use lms;
mysql> source doc/lms.mysql;


2.5.1.4. LMS Configuration (lms.ini)

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

user     = lms
password = your_password

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

Let's stop here and add some stuff to cron, for peace of mind:

12 4 3,10,17,21,28 * * /usr/bin/mysqldump -u lms --password=your-super-secret-password \
              --add-drop-table --add-locks lms > backups/lms-auto-"$(date +%s)".sql

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


2.5.2. PostgreSQL

2.5.2.1. Intro

LMS require PostgreSQL 8.1 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

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 -d -A -P lms
$ /usr/local/pgsql/bin/createdb -E UNICODE -U lms lms
$ /usr/local/pgsql/bin/psql -d lms -U lms -f /lms/doc/lms.pgsql


2.5.2.4. LMS Configuration (lms.ini)

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

type     = postgres
user     = lms
password = password_entered_with_lms_user_creation

Note

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

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

Let's stop here and add some stuff to cron, for peace of mind:

12 4 3,10,17,21,28 * * /usr/bin/pg_dump -U lms --clean \
                       lms --file=backups/lms-auto-"$(date +%s)".sql


2.6. Basic Configuration

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

Note

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

Note

As of version 1.6 and later storing config in lms.ini is beeing treaded as obsolete. The only required values there are from [database] and [directories] sections. 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

  • stats access

  • mailing access

  • Helpdesk (RT) administration

  • Helpdesk (RT) operation

  • accounts management

  • configuration

  • networks and devices management

  • timetable management

  • daemon management and configuration

  • cash operations

  • customers groups 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 and place it in LMS's lib directory. Then set option custom_accesstable in [phpui] section to created file name.

In that way it's possible to define your own rules to allow or deny access for any modules. Module is a name of PHP file in modules directory, given without extension in access rules. For example, it's possible to define rule for invoices display (e.g. for lms-sendinvoices script) in the following way:

<?php
$access['table'][100]['name']      = 'invoices display';
$access['table'][100]['allow_reg'] = '^invoice$';
?>


2.8. Upgrade

Since version 1.5.4 LMS was released in polish language only. If you are upgrading read polish documentation for upgrade description. In newest versions upgrade is very easy. That process has two stages. 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. Invoices

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

For proper work of printouts you need to setup custom options in configuration section [invoices]:

  • header

    Seller. Can use string "\n" for lines separation. Default: empty.

    Example: header = "SuperNet ISP\nNew Street 15\n12-000 City\n"

  • footer

    Invoice footer - e.g. contact information about seller. Footer will be placed at bottom of an invoice, using small font. Like in header option use "\n" to separate lines. Default: empty

    Example: footer = "Internet Service Provider K-27, phone 555-23-23, etc."

  • default_author

    Invoice expositor name (for auto-generated invoices). Default: empty

    Example: default_author = "invoicing expert"

  • cplace

    Invoice issue location (city). Default: empty.

    Example: cplace = Warsaw

  • print_balance_history

    If true on invoice (html) will be printed history of financial operations on customer account. Default: not set.

    Example: print_balance_history = true

  • print_balance_history_limit

    Records number on customer balance list on invoice. Specify last x records. Default: 10.

    Example: print_balance_history_limit = 20000

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


2.9.1.1. HTML

Invoices are printed in html format by default using provided template. In [invoices] section you can also configure:

  • template_file

    Invoice template, which should be placed in templates directory. Default: invoice.html.

    Example: template_file = invoice-mynet.html

  • content_type

    Invoice content-type. If you enter here 'application/octet-stream' then browser will ask to save file on disk, instead of displaying it. It's useful if you use your own template which generate eg. rtf or xls file. Default: 'text/html'

    Example: content_type = application/octet-stream

  • attachment_name

    File name for saving finished invoice printout. WARNING: Setting attachment_name with default content_type will (in case of MSIE) print invoice + prompt for save on disk + bonus browser crash (6.0SP1 on WInXP). Default: empty.

    Example: attachment_name = invoice.xls

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

Note

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


2.9.1.2. PDF

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


2.9.1.3. 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.1.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.2. Transfer forms

Transfer forms it's Polish specific feature. Data for payment form printouts is stored in [finances] configuration section. That is:

name - seller name
shortname - short seller name
address - seller address
zip - seller postal code
city - seller city
account - banking account number
pay_title - title of payment


2.9.3. Cash Receipts


2.9.3.1. HTML

Receipts are printed in html format by default using provided template. 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.3.2. PDF

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


2.9.4. Other documents

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

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

Each wizard must have file info.php with specified structure:

<?php
$engine = array(
    'name' => 'default', 	// wizard (directory) name, lower case 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. Messages

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


3.3.7. 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. Messages

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


3.4.5. 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 or "gd" for graphic images. By default (option not set) LMS will try to generate flash map, and when this fails, t will fallback to GD.

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

Note

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


3.6. IP Networks

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


3.6.1. List

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

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


3.6.2. New Network

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


3.7. Finances

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


3.7.1. Tariffs List

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


3.7.2. New Tariff

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


3.7.3. Payments list

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


3.7.4. New payment

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


3.7.5. Balance sheet

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


3.7.6. New Balance

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

Note

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


3.7.7. Invoices list

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


3.7.8. New Invoice

Allows you to issue an invoice for selected customer manually.


3.7.9. Cash Registry

Cash register can be divided on many registries like cash1, cash2, main cash, bank, etc. On regirstries list are placed all informations 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.10. 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.11. Import

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

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

To setup regular expressions, which suit to your input files you should create PHP script which location you must set in import_config option in [phpui] section. Example values and parameters descriptions are placed in modules/cashimportcfg.php. Default configuration assumes that input data will be in the following format (tab separated):

23.02.2004	Machniak Aleksander	123,45	Internet subscription - 04/2004 ID:0013
15.02.2004	Pain Joseph	123,45	Invoice paid - LMS/34/2004


3.7.12. 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.13. Reports

There are several options for balance sheet printouts:

  • Balance sheet for your network including financial operations for given period, signed by selected LMS user

  • Total invoiceless income for given period

  • Liability report for given day, for all or selected user

  • Sale Registry, which consists of invoices for given period.

  • Cash Report, which consists of cash receipts for given period and/or given registry and cashier.

  • Customer balance sheet for given period.

  • Invoices for given period or/and selected customer.

  • Transfer forms for selected customer or customers group and given balance limit (only for polish forms).


3.8. 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.9. Accounts

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

You can create 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 at least one account type and assign customer to it. Domain name is optional and you'll need it only if you want to support email accounts. Expiration date is also optional, leave it empty to make new account valid forever.

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


3.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 one physical existing account. Basic information about alias and accompanying account is provided on the list. It's possible to sort this list by any highlighted column name and to filter list for given criteria. It's not possible to edit an alias - if it's not desirable anymore you have to erase (remove) it and create new if needed. Add new aliases at the bottom of the list.


3.9.4. Domains

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


3.9.5. Examples

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

Example 3-1. Accounts. Proftpd configuration.

  ServerName	"LMS FTP Server"
  
  #dbname@host:port dbuser dbpass
  SQLConnectInfo lms@localhost:5432 lms mypassword
  
  SQLAuthTypes Crypt Plaintext
  SQLUserInfo passwd login password uid NULL home NULL
  RequireValidShell off
  SQLAuthenticate users
  
  # create user home directory if it doesn't exists yet
  SQLHomedirOnDemand on
  
  # login message
  SQLShowInfo PASS "230" "Last login: %{getlastlogin}"
  SQLLog PASS setlastlogin
  
  # SQLNamedQuery getlastlogin SELECT "CASE lastlogin WHEN 0 THEN '' ELSE FROM_UNIXTIME(lastlogin) END FROM passwd WHERE login='%u'"
  # SQLNamedQuery setlastlogin UPDATE "lastlogin=UNIX_TIMESTAMP() WHERE login='%u'" passwd 
  SQLNamedQuery getlastlogin SELECT "CASE lastlogin WHEN 0 THEN '' ELSE lastlogin::abstime::timestamp::text END FROM passwd WHERE login='%u'"
  SQLNamedQuery setlastlogin UPDATE "lastlogin=EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)) WHERE login='%u'" passwd
  
  # We limit access to valid (not expired) accounts with ftp type
  # SQLUserWhereClause "type & 8 = 8 AND (expdate = 0 OR expdate > UNIX_TIMESTAMP())"
  SQLUserWhereClause "type & 8 = 8 AND (expdate = 0 OR expdate > EXTRACT(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 password FROM passwd, domains WHERE domainid = domains.id
#       AND login='%u' AND domains.name ='%r' AND type & 2 = 2 
#	AND (expdate = 0 OR expdate > UNIX_TIMESTAMP())
sql_select: SELECT password FROM passwd, domains WHERE domainid = domains.id
	AND login='%u' AND domains.name ='%r' AND type & 2 = 2 
	AND (expdate = 0 OR expdate > EXTRACT(EPOCH FROM CURRENT_TIMESTAMP(0)))
password_format: crypt
mech_list: login plain

# authpgsqlrc (or authmysqlrc) (Courier):

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

# main.cf (Postfix):

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

# pgsql_virtual_domains_maps.cf (Postfix):

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

# pgsql_virtual_mailbox_maps.cf (Postfix):

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

# pgsql_virtual_alias_maps.cf (Postfix):

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


3.10. Mailing

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

In message body you can use variables, which will be replaced by customer data:

%customer - name/lastname and forename
%balance - balance value (with sign)
%cid - customer ID
%pin - customer PIN
%last_10_in_a_table - last 10 operations on customer account

Note

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

Note

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


3.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 informations and request statistics are available on queues list. Select and click on chosen queue to display all tickets belonging to it. You can also go to detailed view (including permissions) about queue or remove given queue. Removing queue will also remove all belonging tickets from database.


3.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 classes and LMS will dismiss every unwanted user with HTTP 403 error.

    Example: allow_from = 192.168.0.0/16, 213.25.209.224/27, 213.241.77.29

  • lang

    User interface language code (ISO). IF not set, language will be based on HTML browser settings. Default: en

    Example: lang = pl

  • timeout

    Timeout for WWW session. User will be log out if he won't perform any action in such number of seconds. Default: 600

    Example: timeout = 900

    Warning

    It's not possible to not to have any timeout. If you set this value to zero, you won't be able to use LMS at all!

  • 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

  • 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

  • debug_email

    E-mail address for debugging - messages sent from module 'Mailing' will be delivered to this address instead of sending them to real users.

    Example: debug_email = root@localhost

  • default_zip, default_city, default_address

    Default zip code, city and street used on "new user" form. Useful when we have many users on the same street.

    Example: default_zip = 39-300

  • use_current_payday

    Forces to use current day of month as a payment day. 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 informations 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

  • smtp_host, smtp_port, smtp_username, smtp_password

    Parameters for smtp authorization in mailing. Default: 127.0.0.1:25.

    Example: smtp_host = mail.domain.pl

  • smtp_auth_type

    Smtp authorization method in mailing. By default LMS (exactly PEAR::Net_SMTP) will use the best supported method. Default: none.

    Example: smtp_auth_type = DIGEST-MD5

  • gd_translate_to

    Charset of data that GD library expects (useful if GD need ISO-8859-2 instead of UTF-8 to feed imagetext() function. Default: ISO-8859-2.

    Example: gd_translate_to =

  • check_for_updates_period

    How often to check for LMS updates (in seconds). Default: 86400.

    Example: check_for_updates_period = 604800

  • default_taxrate

    Specify value (not label) of tax rate which will be selected on drop-down lists by default. Default: 22.

    Example: default_taxrate = 22.0

  • 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


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. 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.5. Daemon

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


Chapter 4. Scripts

4.1. Installation

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

For example crontab entry which will execute lms-payments script each day one minute after midnight should take a form of:

1 0 * * *       /usr/sbin/lms-payments 1 > /dev/null

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

Most LMS scripts have following command line options:

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

4.2. List of available scripts

Table 4-1. Executable scripts list

NameDescription
lms-notifyMassive mailing for customer notification
lms-notify-smsNotifies customer about his debt with SMS
lms-cutoffCutoff of customers who are in debt
lms-etherdescMAC address - hostname pair file creation for iptraf
lms-paymentsAccounting subscription fees (periodical) with invoice writeouts
lms-trafficBandwidth consumption calculation
lms-traffic-logiptablesBandwidth probe with iptables
lms-makearpARP table (/etc/ethers) creation
lms-makedhcpconfDHCP server configuration (dhcpd.conf)
lms-makeiptablesConfiguration of iptables firewall rules
lms-makeipchainsConfiguration of ipchains firewall rules
lms-makeopenbsdpfConfiguration of OpenBSD packet filter rules
lms-makeoidentconfConfiguration of oident
lms-sendinvoicesDistribution of invoices to customers
lms-makemacsFirewalling with use of source MAC addresses
lms-makehosts/etc/hosts file creation
lms-makewarningsRedirect rules for customers in debt
lms-makemessagesRedirect rules for customers in debt with warning message
lms-fpingOnline nodes scan
lms-rtparserHelpdesk backend for MUA

4.3. Description and configuration

4.3.1. lms-notify

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


4.3.1.1. Templates

You can use following variables in your templates:

  • %date-m - will be substituted with current month in numerical form with leading zero, eg. 02

  • %date-y - will be substituted with current year, eg. 2003

  • %date_month_name - will be substituted with current month name, eg. March

  • %saldo - will be substituted with current customer balance, eg. 535

  • %abonament - will be substituted with customer's subscription fee, eg. 107

  • %b - customer balance with opposite sign, eg. 107

  • %B - customer balance with real sign, eg. -107

  • %pin - PIN code of the customer

  • %cid - customer ID

  • %last_10_in_a_table - list of last 10 operations on customer's account, eg.

Example 4-1. Lms-notify: example of last 10 customer's operations

-----------+------------------------------------------------------+---------
2003-02-02 | Subscription for month 2003/02                       |  107.00
2003-02-01 | Payment                                              | -107.00
2003-02-01 | Subscription for month 2003/02                       |  107.00
2003-02-01 | Payment                                              | -321.00
2003-01-31 | Subscription for month 2003/01                       |  107.00
2003-01-31 | Subscription for month 2003/01                       |  107.00
2003-01-31 | Subscription for month 2003/01                       |  107.00
-----------+------------------------------------------------------+---------

Example 4-2. Lms-notify: example of mailing template

NOTE: This message has been generated automatically.

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

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

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

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

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

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

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

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

Date       | Description                                          | Amount
%last_10_in_a_table

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

4.3.1.2. Configuration

Configuration of lms-notify should be set in lms.ini file, [notify] section. Following parameters are valid:

  • limit

    Lets you setup limit of customer debt. Email will be sent below that value. Default: limit = 0

    Example: limit = -20

  • mailsubject (mandatory)

    Lets you setup subject of email sent. You can use following templates, with meanings identical to those set in email template: %B, %b, %date-y, %date-m, %last_10_in_a_table. Default: none.

    Example: mailsubject = Debt information

  • mailtemplate (mandatory)

    Lets you setup mail template which will be sent. Default: none.

    Example: mailtemplate = /etc/lms/notifytemplate.txt

  • mailfrom (mandatory)

    Lets you setup email of the sender. Default: none.

    Example: mailfrom = staff@bigpro.com

  • mailfname (mandatory)

    Sender name. Default: none

    Example: mailfname = Administrators

  • mailcharset

    Message character set (Content-Type). Default: UTF-8

    Example: mailcharset = ISO-8859-2

  • smtp_server

    SMTP server to be used when sending emails. Default: 127.0.0.1

    Example: smtp_server = smtp.bigpro.com

  • debug_email (optional)

    Email address for debugging. All email will be sent to this address instead of sending to real customers. Default: not set.

    Example: debug_email = lexx@domain.pl


4.3.2. lms-notify-sms

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

Configuration of lms-notify-sms should be set in lms.ini file, [notify-sms] section. Following parameters are valid:

  • limit

    Lets you setup limit of customer debt. SMS will be sent below that value. Default: 0

    Example: limit = -20

  • smstemplate (mandatory)

    Message template. Default: not set.

    Example: smstemplate = /etc/lms/smstemplate.txt


4.3.3. lms-cutoff

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

Configuration of lms-cutoff should be set in lms.ini file, [cutoff] section. Following parameters are valid:

  • limit (optional)

    Lets you setup limit of customer debt. Customer will be marked as disconnected below that value. Default: 0

    Example: limit = -20

  • message (optional)

    If not empty, that message will be written to warning message field in customer record after cutting him off. You can use %now variable - 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)

    Type of payment. Default: 'TRANSFER'

    Example: paytype = 'CASH'

  • suspension_description (optional)

    Suspension description for suspended liabilities added at the end of comment. Default: ''

    Example: paytype = '(suspension)'

  • comment (optional)

    Description on invoice attached to every periodical assigment

    Default: '%tariff subscription for period %period'

    Some keywords are substitiuted:

    %tariff - subscription name

    %period - period (counted from current day to the last in cycle, in YYYY/MM/DD form)

    %current_month - period form 1st day of current month to the last day

    %desc - tariff description

    Example: comment = 'Subscription for %current_month'

  • 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: Data::Dumper, LWP::UserAgent and MIME::Entity.

Configuration of lms-sendinvoices should be set in lms.ini file, [sendinvoices] section. Following parameters are valid:

  • lms_url

    URL for your LMS installation. Default: http://localhost/lms/

    Example: lms_url = http://lms.mynet.pl

  • lms_user

    LMS user login name. Default: empty

    Example: lms_user = admin

  • lms_password

    LMS user password. Default: empty

    Example: lms_password = my_secret

  • debug_email

    Email address to test (mail will be redirected here). Default: undefined.

    Example: debug_email = admin@mynet.pl

  • sender_name

    Email sender name. Default: undefined.

    Example: sender_name = ASK MyNet

  • sender_email

    Email sender address. Default: undefined.

    Example: sender_email = admin@mynet.pl

  • mail_subject

    Email subject. %invoice variable will be replaced by invoice number. Default: 'Invoice No. %invoice'.

    Example: mail_subject = 'New invoice'

  • mail_body

    Email body. %invoice variable will be replaced by invoice number. Default: 'Attached file with Invoice No. %invoice'.

    Example: mail_body = ''

  • customergroups

    List of (space separated) customer groups, that should be considered while sending invoices. Default: unset - all customers.

    Example: customergroups = group1 group2

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


4.3.11. lms-makemacs

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

Configuration of lms-makemacs should be set in lms.ini file, [macs] section. Following parameters are valid:

  • networks

    List of (space separated) networks, that should be considered while creating configuration file. If unset, configuration will include all networks.

    Example: networks = public-custa public-custb

  • customergroups

    List of (space separated) customer groups, that should be considered while creating configuration file. If unset, configuration will include all groups.

    Example: customergroups = settlement1 settlement2

  • iptables_binary

    Location of iptables binary. Default: /sbin/iptables

    Example: iptables_binary = /usr/local/sbin/iptables

  • config_owneruid

    UID of file owner. Default: 0 (root).

    Example: config_owneruid = 0

  • config_file

    Location of the output file. Default: /etc/rc.d/rc.macs

    Example: config_file = /etc/conf.d/rc.macs

  • config_ownergid

    GID of file owner. Default: 0 (root).

    Example: config_ownergid = 0

  • config_permission

    Permissions of the file. Default: 700 (rwx------).

    Example: config_permission = 700

  • chain

    Chain name to use (if non-standard, it will be created). Default: MACS.

    Example: chain = CHECKMAC

  • redirect_address

    Address and port, where unmatched traffic for http and webcache will be redirected, in address:port format. Default: 127.0.0.1:80.

    Example: redirect_address = 192.168.1.1:3000

  • lock_noaccess

    Should RETURN rule be used for disconnected (cutoff) nodes. Default: 0 (rules are being generated)

    Example: lock_noaccess = 1


4.3.12. lms-makehosts

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

Configuration of lms-makehosts should be set in lms.ini file, [hosts] section. Following parameters are valid:

  • networks

    List of (space separated) networks, that should be considered while creating configuration file. If unset, configuration will include all networks.

    Example: networks = public-custa public-custb

  • customergroups

    List of (space separated) customer groups, that should be considered while creating configuration file. If unset, configuration will include all groups.

    Example: customergroups = settlement1 settlement2

  • config_owneruid

    UID of file owner. Default: 0 (root).

    Example: config_owneruid = 0

  • config_file

    Location of the file. Default: /etc/hosts.

    Example: config_file = /etc/hosts

  • config_ownergid

    GID of file owner. Default: 0 (root).

    Example: config_ownergid = 0

  • config_permission

    Permissions of the file. Default: 644 (rw-r--r--).

    Example: config_permission = 600

  • config_header

    First line in /etc/hosts. Default: 127.0.0.1 localhost localhost.localdomain.

    Example: config_header = 192.168.1.1 ourserver ourserver.ournetwork


4.3.13. lms-makewarnings

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

Configuration of lms-makewarnings should be set in lms.ini file, [warnings] section. Following parameters are valid:

  • networks

    List of (space separated) networks, that should be considered while creating configuration file. If unset, configuration will include all networks.

    Example: networks = public-custa public-custb

  • customergroups

    List of (space separated) customer groups, that should be considered while creating configuration file. If unset, configuration will include all groups.

    Example: customergroups = settlement1 settlement2

  • iptables_binary

    Location of iptables binary. Default: /sbin/iptables

    Example: iptables_binary = /usr/local/sbin/iptables

  • config_owneruid

    UID of file owner. Default: 0 (root).

    Example: config_owneruid = 0

  • config_file

    Location of the file. Default: /etc/rc.d/rc.warnings.

    Example: config_file = /etc/conf.d/rc.warnings

  • config_ownergid

    GID of file owner. Default: 0 (root).

    Example: config_ownergid = 0

  • config_permission

    Permissions of the file. Default: 700 (rwx------).

    Example: config_permission = 700

  • chain

    Custom chain to which rules will be added. Default: WARNINGS.

    Example: chain = WARN

  • redirect_address

    IP address and port, to which all http and webcache traffic will be redirected, for hosts to which warning was enabled in LMS-UI. Default: 127.0.0.1:80.

    Example: redirect_address = 192.168.1.1:3001

  • limit

    Rules are being triggered if customer balance is below this limit. Default: 0

    Example: limit = -85


4.3.14. lms-makemessages

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

Configuration of lms-makemessages should be set in lms.ini file, [messages] section. Following parameters are valid:

  • networks

    List of (space separated) networks, that should be considered while creating configuration file. If unset, configuration will include all networks.

    Example: networks = public-custa public-custb

  • customergroups

    List of (space separated) customer groups, that should be considered while creating configuration file. If unset, configuration will include all groups.

    Example: customergroups = settlement1 settlement2

  • iptables_binary

    Location of iptables binary. Default: /sbin/iptables

    Example: iptables_binary = /usr/local/sbin/iptables

  • config_owneruid

    UID of file owner. Default: 0 (root).

    Example: config_owneruid = 0

  • config_file

    Location of the file. Default: /etc/rc.d/rc.messages.

    Example: config_file = /etc/conf.d/rc.messages

  • config_ownergid

    GID of file owner. Default: 0 (root).

    Example: config_ownergid = 0

  • config_permission

    Permissions of the file. Default: 700 (rwx------).

    Example: config_permission = 700

  • chain

    Custom chain to which rules will be added. Default: MESSAGES.

    Example: chain = MESG

  • redirect_address

    IP address and port, to which all http and webcache traffic will be redirected, for hosts to which warning was enabled in LMS-UI. Default: 127.0.0.1:80.

    Example: redirect_address = 192.168.1.1:3002


4.3.15. lms-fping

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

Configuration of lms-fping should be set in lms.ini file, [fping] section. Following parameters are valid:

  • networks

    List of (space separated) networks, that should be considered while creating configuration file. If unset, configuration will include all networks.

    Example: networks = public-custa public-custb

  • fping_binary

    Location of fping binary. Default: /usr/sbin/fping

    Example: fping_binary = /usr/local/sbin/fping

  • temp_file

    Location of temporary file, where list of hosts for fping will be stored. After script execution, this file is removed. Default: /tmp/fping_hosts.

    Example: temp_file = /tmp/hosts


4.3.16. lms-rtparser

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

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

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

# main.cf file:
header_checks = regexp:/etc/postfix/header_checks

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

# master.cf file:
filter unix - n n - 10 pipe
      -flags=Rq user=nobody argv=/path/to/lms-rtparser
Above method is valid for Postfix version equal or newer than 2.0. Earlier versions doesn't support FILTER in header_checks. You can work around this by using procmail:
# main.cf file:
mailbox_command = /usr/bin/procmail

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

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

:0 A
$DEFAULT

Next example shows how to connect parser to Exim, using system filter:

# exim.conf file:

system_filter_pipe_transport = address_pipe

# system_filter.txt file:

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

Note

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

Configuration of lms-rtparser should be set in lms.ini file, [rt] section. Following parameters are valid:

  • default_queue

    ID of the queue, to which requests should be sent if not specified on command line. If not set queue will be guessed according to recipient address. Command line -q will override this option. Default: undefined.

    Example: default_queue =

  • mail_from

    Sender address for confirmations. If undefined, queue address will be used, to which ticket was assigned. Default: empty.

    Example: mail_from = rt@net.pl

  • mail_from_name

    Sender name for confirmations. Default: undefined.

    Example: mail_from_name = 'BOK SuperLAN'

  • autoreply_subject

    Confirmation subject. You can use replacement variables here: %tid - ticket id and %subject - request subject. Default: "[RT#%tid] Receipt of request '%subject'".

    Example: autoreply_subject = '[RT#%tid] Helpdesk confirmation'

  • autoreply_body

    Confirmation body. You can use replacement variables here; %tid - ticket id and %subject - request subject. Default: 'Your request was registered in our system.\nTicket identifier RT#%tid has been assigned to this request.\nPlease, place string [RT#%tid] in subject field of any\nfurther mail relating to this request.\n.'

    Example: autoreply_body = ''

  • smtp_server

    SMTP server to be used for sending emails. Default: localhost.

    Example: smtp_server = smtp.bigpro.com

  • mail_dir

    Directory where attachments should be saved. This directory will be accessed for read/write both by rtparser user and your Web Server user. If undefined attachments won't be recorded. Default: undefined.

    Example: mail_dir = /usr/local/lms/mail

  • tmp_dir

    Temp directory. By default it will be taken from environment or set to /tmp.

    Example: tmp_dir = /home/user/tmp

  • auto_open

    This will force reopening closed/dead ticket if request is sent to it's ID. Default: Off.

    Example: auto_open = 1

  • newticket_notify

    If enabled script will send notification about new ticket to all users with rights for current queue. Default: Off.

    Example: newticket_notify = 1

  • lms_url

    This link, pointing to corresponding ticket page in UI is appended to the notification about new ticket. Default: http://localhost/lms/.

    Example: lms_url = https://lms.domain.pl/

  • include_customerinfo

    Adds basic customer informations 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.

  • networks

    >List of (space separated) networks, that should be considered while creating configuration file. If unset, configuration will include all networks.

    Example: networks = cust1-publ cust2-publ cust3-priv

Mgc script now loops for each network and performs the following tasks:

  • network_header

    String, which should be put at beginning of network section. Default: empty

    Example: network_header = network %ADDR/%MASK { # Config section for %NAME

  • dst_networks

    List of destination network names, for which dst_network_header variable (see below) will be used. Default: all

    Example: dst_networks = main coalloc

  • dst_network_header

    Lets you to set destination networks header.

    Example: dst_network_header = \tallow to %DADDR/%DMASK;

  • network_body

    This parameter is parsed after network headers and before IP addresses loop.

    Example: network_body = \tnodes {

Mgc script now loops into below rules for each IP address for given range. It takes each IP address and checks if a rule is defined for this address, if yes - it executes first rule that matches. Matches are being parsed in specific order, as described below:

  • ignore

    Lets you setup list of addresses (in address/prefix or address/netmask form, space separated) which should be skipped.

    Example: ignore = 192.168.0.100/32

  • node(IP)

    Allows you to add line for given IP address. IP address should be provided in parenthesis. Each section may have unlimited number of such options.

    Example: node(192.168.0.20) = ??

  • allnodes

    Adds line for each non-ignored IP address.

    Example: allnodes = ??

  • allexistnodes

    Adds line for each IP address that is 'owner' by a computer in database.

    Example: allexistnodes = ??

  • netdevnode

    Adds line for each IP address of network device.

    Example: netdevnode = ??

  • grantednode_priv

    Adds line for each IP address with 'connected' status in database (parsed only for private address classes).

    Example: grantednode_priv = \t\tnode %NAME (%IP/%MAC) unique %ID;

  • grantednode_publ

    Adds line for each IP address with 'connected' status in database (parsed only for public address classes).

    Example: grantednode_publ = \t\tnode %NAME (%IP/%MAC) unique %ID;

  • deniednode_priv

    Adds line for each IP address with 'disconnected' status in database (parsed only for private address classes).

    Example: deniednode_priv = node %NAME (%IP/%MAC) unique %ID deny;

  • deniednode_publ

    Adds line for each IP address with 'disconnected' status in database (parsed only for public address classes).

    Example: deniednode_publ = node %NAME (%IP/%MAC) unique %ID deny;

  • dhcpnode_priv

    Adds line for each IP address within DHCP dynamic range (parsed only for private address classes).

    Example: dhcpnode_priv = node unknown (%IP) reject;

  • dhcpnode_publ

    Adds line for each IP address within DHCP dynamic range (parsed only for public address classes).

    Example: dhcpnode_publ = node unknown (%IP) reject;

  • freeip_priv

    Adds line for each IP address that is not occupied by any computer in database (parsed only for private address classes).

    Example: freeip_priv = node unknown (%IP) lock_as_unused;

  • freeip_publ

    Adds line for each IP address that is not occupied by any computer in database (parsed only for public address classes).

    Example: freeip_publ = node unknown (%IP) lock_as_unused;

  • default_priv

    Default line, which is inserted when none of grantednode or deniednode matches for given IP address (parsed only for private address classes)

    Example: default_priv = node unknown (%IP) lock_as_intruder;

    Note

    Mgc automatically detects if given address belongs to private or public network.

  • default_publ

    Default line, which is inserted when none of grantednode or deniednode matches for given IP address (parsed only for public address classes)

    Example: default_publ = node unknown (%IP) lock_as_intruder;

Mgc now is ready to append final part of the file and execute system command.

  • network_footer

    Adds line for currently processed network.

    Example: network_footer = ??

  • footer_file

    Filename, that should be appended at the end of output file. Default: unset

    Example: footer_file = /etc/lms/myservice_footer

  • footer

    String, which should be put at the end of output file. Default: unset

    Example: footer = # End.

  • post_exec

    System command that should be executed after saving output file.

    Example: post_exec = killall -HUP mydaemon


5.2.4. Configuration variables

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

Computer templates:

  • %IP - IP address

  • %PUBIP - second (public) IP address

  • %PIN - PIN of customer who owns node

  • %ID - ID of computer

  • %MAC - MAC address

  • %SMAC - MAC address in lowercase and without colon separators

  • %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

  • %UPRATE - guaranteed upload rate

  • %DOWNRATE - guaranteed download rate

  • %UPCEIL - maximum upload rate

  • %DOWNCEIL - maximum download rate

  • %CLIMIT - limit of concurrent connections

  • %PLIMIT - maximum number of packets per second

  • %1 %2 %3 %4 - consecutive (left to right) decimal octets of IP address

  • %NID - network ID where computer belongs

  • %NNAME - network name, in uppercase

  • %nname - network name, in lowercase

  • %NADDR - network address

  • %NIFACE - network interface

  • %NMASK - network mask

  • %NGATE - network gateway IP address

  • %NDNS - primary DNS server IP address

  • %NDNS2 - secondary DNS server IP address

  • %NDOMAIN - domain name of the network

  • %NWINS - WINS server IP address

  • %NDHCPS - first IP address of dynamic DHCP range

  • %NDHCPE - last IP address of dynamic DHCP range

Network templates (for sections relevant to networks only):

  • %ID - network ID

  • %NAME - network name, in uppercase

  • %name - network name, in lowercase

  • %ADDR - network IP address

  • %IFACE - network interface

  • %MASK - network IP mask

  • %GATE - network gateway IP address

  • %DNS - primary DNS server IP address

  • %DNS2 - secondary DNS server IP address

  • %DOMAIN - domain name of the network

  • %WINS - WINS server IP address for the network

  • %DHCPS - first IP address of dynamic DHCP range for the network

  • %DHCPE - last IP address of dynamic DHCP range for the network

Note

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

Templates which can be used everywhere:

  • %DATE - date in YYYYMMDD format;

  • %TIME - time in HHMM format;

  • %TIMES - time in HHMMSS format;

  • %UTIME - time in unix timestamp format;


5.3. Examples of use

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

Example 5-1. Lms-mgc: Example instance

You should start with creating new mgc section in lms-mgc.ini, with relevant name ('ipchains') and put a simple masquerade rules, per IP, inside:

[mgc:ipchains]
outfile           = /etc/rc.d/rc.masq
outfile_perm      = 700
header            = #!/bin/sh\n/sbin/ipchains -F\n/sbin/ipchains -X\n/sbin/ipchains -P forward DENY
grantednode_priv  = /sbin/ipchains -A forward -s %IP -j MASQ
post_exec         = /etc/rc.d/rc.masq
You can also add your ipchains subsection to main mgc section, so that it executes it by default:
[mgc]
instances         = ipchains

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


Chapter 6. LMS Daemon

6.1. Basics

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


6.1.1. Requirements

LMS Daemon requires:

  • LMS user interface installation

  • libmysqlclient shared library (included in full MySQL installation or respective "devel" package) or libpq shared library in case of PostgreSQL database use.

  • libdl shared library (present in every modern distribution)

  • C compiler (gcc-2.95.x or higher)

  • ggnotify module needs libgadu library and header files

  • parser module needs flex and bison (version 1.875 or newer).


6.1.2. Installation

You have to setup some configure options prior to compilation, that can be listed with --help flag of ./configure script (default values shown in brackets):

  --help                help
  --enable-debug0       SQL queries logging (disabled)
  --enable-debug1       events logging (disabled)
  --with-pgsql          enables using of PostgreSQL database (disabled)
  --with-mysql          enables using of MySQL database (enabled)
  --prefix=PREFIX       program and modules install directory (/usr/local)
  --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 must correspond to the
                           one specified in hosts configuration in UI
--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

NameDescription
systemShell commands execution
parserUniversal T-Script scripts parser
dhcpConfiguration of DHCP server
cutoffDisconnection of indebted users
dnsConfiguration of DNS server
ethers/etc/ethers file creation
hostfileUniversal module (eg. making iptables rules)
notifyEmail notify about payments
ggnotifyGadu-Gadu (polish internet messenger) notify about payments
paymentsPayments accounting
oidentConfiguration of oident daemon
tcMaking HTB rules
trafficInternet link usage statistics
pingerUsers 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. 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. Default: 'TRANSFER'.

    Example: paytype = 'CASH'


6.2.4. Notify

6.2.4.1. Description

Module 'notify' is designed to inform customers about their debt using electronic mail. Current customer balance is compared to 'limit' option, if it's beneath that limit - message will be sent. Message content is taken from template, which may include the following variables:

  • %saldo - current customer balance (also %b)

  • %B - absolute value of current customer balance

  • %pin - customer PIN

  • %name - customer forename

  • %lastname - company name or customer lastname

  • %last_10_in_a_table - last 10 operations on customer account


6.2.4.2. Configuration

Configuration options for 'notify' module are presented below:

  • template

    Location of message template file. Default: empty.

    Example: template = modules/notify/sample/mailtemplate

  • file

    Location of temporary file. Default: /tmp/mail

    Example: file = /tmp/mail.txt

  • command

    Shell command for sending an e-mail. '%address' will be replaced by customer e-mail address. Default: 'mail -s "Liabilities Information" %address < /tmp/mail'.

    Example: command = 'mail -s "You must pay or ..." $address < /tmp/mail.txt'

  • limit

    Message is sent when customer balance will decrease below value defined in this option. Default: 0

    Example: limit = -20

  • debug_mail

    If set, all messages goes to this address, instead of sending them to customers. Useful for testing. Default: empty.

    Example: debug_mail = tester@my.net


6.2.5. Ggnotify

6.2.5.1. Description

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

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


6.2.5.2. Configuration

Options similar to 'notify' module might be also used here:

  • template

    Location of message template file. Default: empty.

    Example: template = modules/notify/sample/mailtemplate

  • uin

    Gadu-gadu identifier number of message sender. Default: empty.

    Example: uin = 1234567

  • password

    Password for account specified by 'uin'. Default: empty.

    Example: password = "my_HURD.password"

  • limit

    Message is sent when customer balance will decrease below value defined in this option. Default: 0

    Example: limit = -20

  • debug_uin

    If is set, all messages will go to that 'uin'. Default: empty.

    Example: debug_uin = 7654321


6.2.6. Cutoff

6.2.6.1. Description

Cutoff do change nodes status to 'disconnected' and/or enable warnings for customers, which have debts greater than specified limit. 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 value. Default: 0.

    Example: limit = -20

  • command

    Specifies system command, that is executed if at least one customer should be disconnected or warning should be enabled. Default: empty.

    Example: command = 'lmsd -qi firewall'

  • warning

    Enable warning for disconnected customer and write him WWW browser message specified in this option. If empty, warning will be not enabled. Date in message is substituted providing '%time' variable. Default: 'Blocked automatically due to payment deadline override 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

  • 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


6.2.7. DHCP

6.2.7.1. Description

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


6.2.7.2. Configuration

Most of configuration parameters match with parts of DHCP configuration file, and in typical environment doesn't need any changes:

  • file

    Location of DHCP server configuration file. Default: /etc/dhcpd.conf.

    Example: file = /etc/dhcp/dhcpd.conf

  • command

    Shell command executed after config file creation. Default: 'killall dhcpd; /usr/sbin/dhcpd'.

    Example: command = '/etc/rc.d/rc.dhcpd restart'

  • begin

    File header. Default: empty.

    Example: begin = "authoritative;"

  • end

    File footer. Default: empty.

    Example: end = ""

  • subnet_start

    Subnet header. '%a' - name, '%m' - mask. Default: "subnet %a netmask %m {\ndefault-lease-time 86400;\nmax-lease-time 86400;".

    Example: subnet_start = "subnet %a netmask %m {default-lease-time 3600;"

  • subnet_end

    Subnet footer. Default: "}".

    Example: subnet_end = '\t}'

  • subnet_gateway

    Subnet gateway. '%i' will be changed to IP address. Default: "option routers %i;".

    Example: subnet_gateway = "option routers %i"

  • subnet_dns

    Subnet DNS servers. '%i - dns addresses. Default: "option domain-name-servers %i;".

    Example: subnet_dns = "option domain-name-servers 192.168.0.1"

  • subnet_domain

    Subnet domain name. '%n' - name. Default: 'option domain-name "%n";'.

    Example: subnet_domain = "option domain-name test.%n;"

  • subnet_wins

    WINS servers. '%i' - server IP address. Default: "option netbios-name-servers %i;".

    Example: subnet_wins = ""

  • subnet_range

    Subnet address range. '%s' - initial address, '%e' - end of range. Default: "range %s %e;".

    Example: subnet_range = "range %s %e;"

  • host

    Hosts parameters, where '%n' - host name, '%m' - MAC, '%i' - IP address. Default: "\thost %n {\n\t\thardware ethernet %m; fixed-address %i; \n\t}".

    Example: host = "host %n {hardware ethernet %m; fixed-address %i;}"

  • networks

    List of network names that should be included in configuration (case insensitive). Default: empty (all networks).

    Example: networks = "lan1 lan2"

  • customergroups

    List of customers groups that should be included in configuration (case insensitive). Default: empty (all groups).

    Example: customergroups = "group1 group2"


6.2.8. Hostfile

6.2.8.1. Description

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


6.2.8.2. Configuration

The following templates might be used for 'grantedhost', 'deniedhost', 'public_grantedhost' and 'public_deniedhost' options replaced with actual data from database:

%i - IP address,
%ipub - public IP address,
%id - node ID,
%m - MAC address,
%n - host name,
%p - node (computer) password,
%info - node description,
%domain - domain,
%net - network name,
%gw - gateway address of network,
%if - network's interface,
%mask - network mask,
%addr - network's address,
%dns, %dns2 - DNS server addresses,
%wins - WINS server address,
%i16 - IP's last octet in hex,
%i16pub - public IP's last octet in hex.
This module has following options:

  • file

    Location of generated file. Default: /tmp/hostfile

    Example: file = /etc/rc.d/rc.firewall

  • command

    Shell command(s) executed after 'file' creation. Default: empty

    Example: command = '/bin/sh /etc/rc.d/rc.firewall'

  • begin

    File header. Default: "/usr/sbin/iptables -F FORWARD\n"

    Example: begin = "IPT=/usr/sbin/iptables \n$IPT -F FORWARD\n"

  • end

    File footer. Default: "/usr/sbin/iptables -A FORWARD -J REJECT\n"

    Example: end = "$IPT -A FORWARD -J REJECT\n"

  • grantedhost

    Line with rule(s) for connected node. Default: "/usr/sbin/iptables -A FORWARD -s %i -m mac --mac-source %m -j ACCEPT\n"

    Example: grantedhost = "$IPT -A FORWARD -s %i -m mac --mac-source %m -j ACCEPT\n"

  • deniedhost

    Line with rule(s) for disconnected node. Default: "/usr/sbin/iptables -A FORWARD -s %i -m mac --mac-source %m -j REJECT\n"

    Example: deniedhost = "$IPT -A FORWARD -s %i -m mac --mac-source %m -j REJECT\n"

  • public_grantedhost

    Line with rule(s) for connected node with specified public IP. By default rule specified in 'grantedhost' option.

    Example: public_grantedhost = "$IPT -A FORWARD -s %i -m mac --mac-source %m -j ACCEPT\n$IPT -t nat -A PREROUTING -p tcp -d %ipub -j DNAT --to-destination %i\n$IPT -t nat -A POSTROUTING -s %i -j SNAT --to-source %ipub\n"

  • public_deniedhost

    Line with rule(s) for disconnected node with specified public IP. By default rule specified in 'deniedhost' option.

    Example: public_deniedhost = ""

  • networks

    List of network names which members should be included in config (case insensitive). Default: empty (all networks).

    Example: networks = "lan1 lan2"

  • customergroups

    List of customer group names which members should be included in config (case insensitive). Default: empty (all groups).

    Example: customergroups = "group1 group2"

  • skip_dev_ips

    If enabled (yes, true) network devices (devices that does not belong to customers) will be ignored (omitted). Default: yes

    Example: skip_dev_ips = no


6.2.9. Traffic

6.2.9.1. Description

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


6.2.9.2. Configuration

There is only one available option and it's mandatory:

  • file

    Location of file with firewall stats. Default: /var/log/traffic.log

    Example: file = /tmp/log


6.2.10. Tc (HTB)

6.2.10.1. Description

Generate script containing iptables and tc rules for traffic control ie. band and customer connections limits. Rules for nodes can be freely defined and used not only for traffic control. Principle of operation of this module is following: First of all all customers data is being retrieved. Totals for limitations (uprate, downrate, upceil, downceil, connection limit) are being calculated for each customer. Then, loop is performed to check networks and groups (if specified). If limit values are not zeroes rules are written to file with variables replacement. The following variables can be used in rules: %name - host name, %i - IP address, %m - MAC, %if - network interface, %uprate, %downrate, %upceil, %downceil, %plimit, %climit, %i16 - IP's last octet heximal representation, 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 99000kbit quantum 1500
    $TC class add dev $LAN parent 1:1 classid 1:2 htb rate   500kbit ceil   500kbit
    $TC class add dev $LAN parent 1:1 classid 1:3 htb rate 98500kbit ceil 98500kbit prio 9 quantum 1500
    $TC qdisc add dev $LAN parent 1:3 esfq perturb 10 hash dst
    # priorities for ICMP, TOS 0x10 and ports 22 and 53
    $TC class add dev $LAN parent 1:2 classid 1:20 htb rate 50kbit ceil 500kbit $BURST prio 1 quantum 1500
    $TC qdisc add dev $LAN parent 1:20 esfq perturb 10 hash dst
    $TC filter add dev $LAN parent 1:0 protocol ip prio 2 u32 match ip sport 22 0xffff flowid 1:20
    $TC filter add dev $LAN parent 1:0 protocol ip prio 2 u32 match ip sport 53 0xffff flowid 1:20
    $TC filter add dev $LAN parent 1:0 protocol ip prio 1 u32 match ip tos 0x10 0xff flowid 1:20
    $TC filter add dev $LAN parent 1:0 protocol ip prio 1 u32 match ip protocol 1 0xff flowid 1:20
    # server -> LAN
    $TC filter add dev $LAN parent 1:0 protocol ip prio 4 handle 1 fw flowid 1:3
    
    # outgoing traffic
    $TC qdisc add dev $WAN root handle 2:0 htb default 11 r2q 1
    $TC class add dev $WAN parent 2:0 classid 2:1 htb rate 120kbit ceil 120kbit
    # priorities for ACK, ICMP, TOS 0x10, ports 22 and 53
    $TC class add dev $WAN parent 2:1 classid 2:10 htb rate 60kbit ceil 120kbit prio 1 quantum 1500
    $TC qdisc add dev $WAN parent 2:10 esfq perturb 10 hash dst
    $TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip protocol 6 0xff \
    match u8 0x05 0x0f at 0 match u16 0x0000 0xffc0 at 1 match u8 0x10 0xff at 33 flowid 2:10
    $TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip dport 22 0xffff flowid 2:10
    $TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip dport 53 0xffff flowid 2:10
    $TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip tos 0x10 0xff flowid 2:10
    $TC filter add dev $WAN parent 2:0 protocol ip prio 1 u32 match ip protocol 1 0xff flowid 2:10
    # server -> Internet
    $TC class add dev $WAN parent 2:1 classid 2:11 htb rate 30kbit ceil 120kbit prio 2 quantum 1500
    $TC qdisc add dev $WAN parent 2:11 esfq perturb 10 hash dst
    $TC filter add dev $WAN parent 2:0 protocol ip prio 3 handle 1 fw flowid 2:11
    $TC filter add dev $WAN parent 2:0 protocol ip prio 9 u32 match ip dst 0/0 flowid 2:11

    Example: begin = "#!/bin/bash\n$TC=/usr/local/sbin/tc\n"

  • end

    Script footer. Default:

    }
    
    case "$1" in
        'start')
         start
        ;;
        'stop')
         stop
        ;;
        'status')
         echo "WAN Interface"
         echo "============="
         $TC class show dev $WAN | grep root
         $TC class show dev $WAN | grep -v root | sort | nl
         echo "LAN Interface"
         echo "============="
         $TC class show dev $LAN | grep root
         $TC class show dev $LAN | grep -v root | sort | nl
        ;;
        *)
         echo -e "\nUsage: rc.htb start|stop|status"
        ;;
    esac

    Example: end = ""

  • one_class_per_host

    Specify htb class creation policy. By default all computers of customer will be placed in one class. Setting it to 'true' will effect in that rules specified in host_htb_up and host_htb_down will be generated for all customer's computers (with different value of '%x'). Rules host_mark_down, host_mark_up, host_plimit and host_climit are generated for each node regardless of this option setting. Default: false

    Example: one_class_per_host = 1

  • host_mark_down

    Mark rule for each offline computer. Default:

    # %n
    $IPT -t mangle -A LIMITS -d %i -j MARK --set-mark %x

    Example: host_mark_down = ""

  • host_mark_up

    Mark rule for each computer. Default:

    $IPT -t mangle -A LIMITS -s %i -j MARK --set-mark %x

    Example: host_mark_up = ""

  • host_htb_down

    Rules for each computer executed when uprate and downrate value is above zero. Default:

    $TC class add dev $LAN parent 1:2 classid 1:%x htb rate %downratekbit ceil %downceilkbit $BURST prio 2 quantum 1500
    $TC qdisc add dev $LAN parent 1:%x esfq perturb 10 hash dst
    $TC filter add dev $LAN parent 1:0 protocol ip prio 5 handle %x fw flowid 1:%x

    Example: host_htb_down = ""

  • host_htb_up

    Rules for each computer executed when uprate and downrate value is above zero. Default:

    $TC class add dev $WAN parent 2:1 classid 2:%x htb rate %upratekbit ceil %upceilkbit $BURST prio 2 quantum 1500
    $TC qdisc add dev $WAN parent 2:%x esfq perturb 10 hash dst
    $TC filter add dev $WAN parent 2:0 protocol ip prio 5 handle %x fw flowid 2:%x

    Example: host_htb_up = ""

  • host_climit

    Rule with simultaneous TCP connections limit. Executed when climit value is above zero. Default:

    $IPT -t filter -I FORWARD -p tcp -s %i -m connlimit --connlimit-above %climit -m ipp2p --ipp2p -j REJECT

    Example: host_climit = "$IPT -t filter -I FORWARD -p tcp -s %i -m connlimit --connlimit-above -j REJECT"

  • host_plimit

    Rule with limiting of packets in time unit (here second). Executed when plimit value is above zero. Default:

    $IPT -t filter -I FORWARD -p tcp -d %i -m limit --limit %plimit/s -m ipp2p --ipp2p -j ACCEPT
    $IPT -t filter -I FORWARD -p tcp -s %i -m limit --limit %plimit/s -m ipp2p --ipp2p -j ACCEPT

    Example: host_plimit = ""

  • networks

    List of network names that should be included in configuration (case insensitive). Default: empty (all networks).

    Example: networks = "lan1 lan2"

  • customergroups

    List of customer groups that should be included in configuration (case insensitive). Default: empty (all groups).

    Example: customergroups = "group1 group2"


6.2.11. Dns

6.2.11.1. Description

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


6.2.11.2. Configuration

  • forward-patterns

    Directory with zone templates. Default: forward.

    Example: forward-patterns = /dns/patterns/forward

  • reverse-patterns

    Directory with reverse zone templates. Default: reverse.

    Example: reverse-patterns = /dns/patterns/revers

  • generic-forward

    Default template. It will be used if directory specified by 'forward-patterns' doesn't contain a file with name corresponding to network domain name. Default: modules/dns/sample/forward/generic.

    Example: generic-forward = /dns/patterns/forward

  • generic-reverse

    Default template. It will be used if directory specified by 'reverse-patterns' doesn't contain a file with name corresponding to network IP address. Default: modules/dns/sample/reverse/generic.

    Example: generic-reverse = /dns/patterns/forward

  • forward-zones

    Directory for generated zone files. Default: modules/dns/sample/out/forward.

    Example: forward-zones = /dns/forward

  • reverse-zones

    Directory for generated reverse zone files. Default: modules/dns/sample/out/reverse.

    Example: reverse-zones = /dns/reverse

  • host-reverse

    Line in reverse zone file for each computer of given network. Default: "%n IN A %i\n".

    Example: host-reverse = "\t %n IN A %i\n"

  • host-forward

    Line in zone file for each computer of given network. Default: "%c IN PTR %n.%d.\n".

    Example: host-forward = "\t %c IN PTR %n.%d.\n"

  • conf-pattern

    Location of main template for server configuration file. Default: modules/dns/sample/named.conf.

    Example: conf-pattern = /dns/patterns/named.conf

  • conf-output

    Location of main configuration file. Default: /tmp/named.conf.

    Example: conf-output = /etc/named.conf

  • conf-forward-entry

    Entry for each zone in main configuration file. Default: 'zone "%n" {\ntype master;\n file "forward/%n"; \nnotify yes; \n}; \n'.

    Example: conf-forward-entry = 'zone "%n" { \n\ttype master; \n\tfile "forward/%n"; \n\tnotify yes; \n}; \n'

  • conf-reverse-entry

    Entry for each reverse zone in main configuration file. Default: 'zone "%c.in-addr.arpa" { \ntype master; \nfile "reverse/%i"; \nnotify yes; \n}; \n'.

    Example: conf-revers-entry = 'zone "%c.in-addr.arpa" { \n\ttype master; \n\tfile "reverse/%i"; \n\tnotify yes; \n}; \n'

  • command

    Shell command executed after files creation. Default: empty.

    Example: command = "killall -HUP named"

  • networks

    List of network names that should be included in configuration (case insensitive). Default: empty (all networks).

    Example: networks = "lan1 lan2"

  • customergroups

    List of customer (user) groups that should be included in configuration (case insensitive). Default: empty (all groups).

    Example: customergroups = "group1 group2"


6.2.12. Ethers

6.2.12.1. Description

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


6.2.12.2. Configuration

Basic options:

  • file

    Location of output file. Default: /etc/ethers.

    Example: file = /tmp/ethers

  • command

    Shell command to execute after config file creation. Default: 'arp -f /etc/ethers'.

    Example: command = ""

  • dummy_macs

    If you set to 'yes', disconnected computers will get MAC '00:00:00:00:00:00'. Default: "no".

    Example: dummy_macs = yes

  • networks

    List of network names that should be included in configuration (case insensitive). Default: empty (all networks).

    Example: networks = "lan1 lan2"

  • customergroups

    List of customer groups names that should be included in configuration (case insensitive). Default: empty (all groups).

    Example: customergroups = "group1 group2"


6.2.13. Oident

6.2.13.1. Description

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


6.2.13.2. Configuration

And here are the options of oident:

  • begin

    Text inserted on the beginning of file. Default: empty.

    Example: begin = "#Auto-generated\n"

  • end

    Text inserted on the end of file. Default: empty.

    Example: end = ""

  • host

    Line of text for each of computers. Default: "%i\t%n\tUNIX".

    Example: host = "%i %n WINDOWS"

  • file

    Configuration file. Default: /etc/oidentd.conf.

    Example: file = /tmp/identd.conf

  • networks

    List of networks. Default: empty (all networks).

    Example: networks = 'lan1 lan2'

  • command

    Shell command(s) to execute after file creation. Default: empty.

    Example: command = "killall -HUP oidentd"


6.2.14. Pinger

6.2.14.1. Description

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

Note

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


6.2.14.2. Configuration

Pinger has only one config option:

  • networks

    List of network names. Default: empty (all networks).

    Example: networks = 'lan1 lan2'


6.2.15. Parser

6.2.15.1. Introduction

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

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

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


6.2.15.2. Configuration

Parser has following options:

  • script

    Contents of script. Default: empty.

    Example: script = '{var=1}variable var={var}'

  • file

    Location of output file. Default: empty.

    Example: file = /tmp/parser.out

  • command

    Shell command to execute after script compilation. Default: empty

    Example: command = "sh /tmp/parser.out"


6.3. T-Script

6.3.1. Introduction

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

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


6.3.2. Syntax

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


6.3.2.1. Expressions and operators

  • Literal inside quotes. 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 informations
    message - warning contents
    warning - warning status (status of all customer's nodes summary)
    access - accessibility status (status of all customer's nodes summary)
    balance - customer's balance

  • NODES - nodes list (and network devices addresses):

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

NameDescription
backupsBackup copies of LMS database
binExecutable lms-* Perl scripts
contribLMS user's contributions
daemonA.L.E.C's LMS Daemon
develDevelopers' scripts to build LMS package
docLMS Documentation
documentsDocuments archive
imgUser Interface Images
libSet of LMS and Smarty libraries
modulesUser Interface Modules
sampleSample scripts, configs and additions
templatesUser Interface Theme
templates_cSmarty Theme compilation directory

7.2. Database structure

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


7.2.1. LMS users ('users')

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

7.2.2. Customers ('customers')

id - serial number
lastname - last/company name
name - first name
status - customer status (3-connected, 2-awaiting, 1-prospect)
email - email address
pin - pin number (for authentication)
address - street address (street, apartment, flat, etc)
zip - zip code
city - location (city)
ten - tax exempt number
ssn - social security number
regon - business registration number
rbe - register of business entities
icn - identity card number
info - additional informations
notes - notes
serviceaddr - correspondence address
creationdate - record creation date
moddate - record modification date
creatorid - serial of LMS user who created this record
modid - serial of LMS user last modification this record
deleted - if is deleted from database boolean (0/1)
message - message to be displayed if warnings enabled

7.2.3. Customer groups ('customergroups')

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

7.2.4. Customer groups - 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

7.2.7. Computers and network devices ('nodes')

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

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

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

7.2.9. Network connections ('netlinks')

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

7.2.10. Financial operations ('cash')

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

7.2.11. Import of financial operations ('cashimport')

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

7.2.12. Subscription fees ('tariffs')

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

7.2.13. Custom liabilities ('liabilities')

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

7.2.14. 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.15. Financial assignments ('assignments')

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

7.2.16. Nodes-tariffs assignments ('nodeassignments')

id - serial number
assignmentid - financial assignment serial number
nodeid - node serial number

7.2.17. 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.18. 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.19. 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.20. 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.21. 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 informations

7.2.22. 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
paytime - deadline in days
paytype - payment method (cash/transfer/etc.)
customerid - customer (buyer) serial number
userid - user serial number
name - name of customer
address - address of customer
ssn - SSN of customer
ten - Tax Exempt Number of customer
zip - zip code of customer
city - location of customer
closed - is document (invoice) closed (accounted)? (0/1)
reference - document ID reference
reason - e.g. invoice note reason

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

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

7.2.24. Invoices ('invoicecontents')

docid - invoice serial number
itemid - invoice item identifier
value - amount
discount - discount percentage
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.25. Cash Receipts ('receiptcontents')

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

7.2.26. 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.27. Customers contacts ('customer contacts')

id - serial number
customerid - customer serial number
phone - phone number
name - contact name/description

7.2.28. 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

7.2.29. Domains ('domains')

id - serial number
name - domain name
description - comments

7.2.30. Aliases ('aliases')

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

7.2.31. Bandwidth consumption statistics ('stats')

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

7.2.32. Helpdesk - Request Tracking ('rtqueues')

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

7.2.33. 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 - LMS user serial number (ticket owner)
createtime - timestamp of report

7.2.34. 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.35. Helpdesk - Request Tracking - continued... ('rtattachments')

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

7.2.36. 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.37. 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.38. 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.39. Timetable - events ('events')

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

7.2.40. Timetable - assignments ('eventassignments')

eventid - event identifier
userid - user identifier

7.2.41. Sessions ('sessions')

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

7.2.42. Hosts ('hosts')

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

7.2.43. Daemon configuration - instances ('daemoninstances')

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

7.2.44. Daemon configuration - options ('daemonconfig')

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

7.2.45. 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 informations can be obtained, by issuing (in mysql shell):

      mysql> show table status;
      
      ...| Avg_row_length | Data_length | Max_data_length | Index_length |
      ...|             44 |       24136 |      4294967295 |        19456 |

      See that free space is about 175 000 time more than currently used, so until you plan to have 100000 users, you're pretty safe in this matter :-)

  • PostgreSQL

    • Database size:

      PostgreSQL stores data in 8kB blocks. Number of blocks in bound to 32-bit number with sign, which gives maximum table size of 16 terabytes. Filesystem restrictions are avoided by keeping data in slices, 1GB each.

    • Number of records:

      PostgreSQL does not have row number limit for tables, however COUNT returns 32-bit number, so for tables longer that 2 billions of records this function will return wrong value (at least in version 7.1).


Chapter 8. Extensions

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


8.1. Customer account

8.1.1. Intro

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

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

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


8.1.2. Installation

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


8.2. Customer account 2

8.2.1. Intro

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

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

It also allows aquiring and printing invoices by customers


8.2.2. Installation

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


8.3. SQL Panel

8.3.1. Intro

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

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


8.3.2. Installation

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


8.4. Squid redirector

8.4.1. Intro

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

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


8.4.2. Installation

Let's start from configuring squid (squid.conf):

# 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. FAQ

9.1. My network device map does not show up. What to do?
9.2. How to add two computers with the same IP?
9.3. How to add two computers with the same MAC?
9.4. I see following error: Can't locate Config/IniFiles.pm in @INC ...What should I do?
9.5. I make few corrections. Do you accept any patches?
9.6. What is current version of LMS, which one i should use?
9.7. How to unsubscribe from the mailing list?
9.8. Insecure $ENV{BASH_ENV} while running -T switch...

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

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

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

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

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

Check documentation. You probably look for allow_mac_sharing = 1.

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

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

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

You should post it to our mailing list. Attach your patches (preferably to current cvs version, use unified diff format) along with short description on what your code does. Eg.

$ cd lms
$ cvs -z7 diff -u > /tmp/my_patch.patch
If you're interested into joining LMS developers team, please apply on the mailing list. You should however first make a good impression and stay on the list for a while, that may prove your skills, before asking us for cvs account.

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

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

Archive of all LMS versions can be found here: 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.

9.7. How to unsubscribe from the mailing list?

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

9.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.