1.2.1. LMS Developers

• PHP Code:

  Lukasz 'Baseciq' Mozer

  Michal 'DziQs' Zapalski

  Radoslaw 'Warden' Antoniuk

  Krzysztof 'hunter' Drewicz

  Marcin 'Lexx' Krol

  Aleksander 'A.L.E.C' Machniak

  Konrad 'kondi' Rzentarzewski

• C Code:

  Aleksander 'A.L.E.C' Machniak

  Marcin 'Lexx' Krol

• Perl Code:

  Lukasz 'Baseciq' Mozer

  Michal 'DziQs' Zapalski

  Maciej 'agaran' Pijanka

  Krzysztof 'hunter' Drewicz

• Design:

  Lukasz 'Baseciq' Mozer

• HTML, JavaScript, CSS:

  Lukasz 'Baseciq' Mozer

  Pawel 'Bob_R' Czerski

  Pawel 'sickone' Kisiela

  Konrad 'kondi' Rzentarzewski

• Images:

  Piotr 'Pierzak' M.

  Grzegorz 'byko' Cichowski

  Kuba 'kflis' Flis

  Lukasz 'Baseciq' Mozer

  Jakub 'Jimmac' Steiner

• MySQL Support:

  Kuba 'shasta' Jankowski

  Radoslaw 'Warden' Antoniuk

  Przemyslaw Babinski

• PostgreSQL Support:

  Aleksander 'A.L.E.C' Machniak

• Web Page & Documentation:

  Aleksander 'A.L.E.C' Machniak

  Kuba 'shasta' Jankowski

  Grzegorz 'JaBBaS' Dziegielewski

  Lukasz 'Baseciq' Mozer

  Marcin 'Lexx' Krol

  Konrad 'kondi' Rzentarzewski

• Beta testing:

  Grzegorz 'byko' Cichowski

  Radoslaw 'Warden' Antoniuk

  Tomasz 'dzwonek' Dzwonkowski

  Sebastian 'Victus' Frasunkiewicz

  Kuba 'kflis' Flis

  Krystian 'UFOczek' Kochanowski

  Grzegorz 'JaBBaS' Dziegielewski

  Andrzej 'chsh' Gradziel

1.2.2. Others

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

1.4.1. Contact

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

1.4.2. Ideas and Bugs Reports

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

1.4.3. Newest version

Newest version of LMS can be downloaded from CVS repository utilizing WWW interface at cvs.rulez.pl, or with CVS tools (anonymous access, empty password):

cvs -d :pserver:cvs@cvs.rulez.pl:/home/cvsroot login
cvs -d :pserver:cvs@cvs.rulez.pl:/home/cvsroot co lms
cvs -d :pserver:cvs@cvs.rulez.pl:/home/cvsroot logout

1.4.4. Changelog

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

1.4.5. Commercial Support

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

2.2.1. Web Server

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

2.2.2. PHP Interpreter

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

• pcre, posix,

• zlib (for compressed backups),

• gd or ming (for network map),

• mysql or pgsql (for db support),

• iconv (for pdf printouts and latin-utf conversion),

• PEAR::Mail (which require PEAR::Net_SMTP and PEAR::Net_Sockets) for mailing.

2.2.3. Database Server

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

PostgreSQL in version 7.3.x or higher is supported.

2.2.4. Smarty Library

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

2.2.5. Perl

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

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

• Config::IniFiles,

• DBI,

• DBD-mysql (if you use MySQL),

• DBD-Pg (if you use Postgres),

2.2.6. C Compiler

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

2.2.7. Web Browser

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

2.5.1. MySQL

$ ./configure --prefix=/usr/mysql
$ make
$ make install
$ /usr/mysql/bin/mysql_install_db
$ chown mysql -R /usr/mysql/var
$ /usr/mysql/bin/safe_mysqld &
$ /usr/mysql/bin/mysqladmin -u root password new_password

mysql -u[user name with database creation rights] -p
Enter password:[just enter password :)]
mysql> CREATE DATABASE lms /*!40101 CHARACTER SET utf8 COLLATE utf8_polish_ci */;
mysql> GRANT USAGE ON lms.* TO lms@localhost;
mysql> GRANT select,insert,update,delete,create,alter,drop ON lms.* TO lms@localhost IDENTIFIED BY '[your_password]';
mysql> flush privileges;
mysql> use lms;
mysql> source doc/lms.mysql;

user     = lms
password = your_password

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

2.5.2. PostgreSQL

$ ./configure --enable-locale
$ gmake
$ su
$ gmake install
$ adduser postgres
$ mkdir /usr/pgsql/data
$ chown postgres /usr/pgsql/data
$ su - postgres
$ /usr/pgsql/bin/initdb -D /usr/pgsql/data --locale=pl_PL.UTF-8
$ /usr/pgsql/bin/postmaster -D /usr/pgsql/data >logfile 2>&1 &

$ /usr/pgsql/bin/createuser -d -A -P lms
$ /usr/pgsql/bin/createdb -E UNICODE -U lms lms
$ /usr/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

The need for password actually depends on Postgres users authentication configuration found in /usr/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.1. Section [database] - Database Settings

• type

  Database type. Currently in 100% are supported 'mysql' and 'postgres'. Default: mysql

  Example: type = mysql

• host

  Host where database is running. Usually 'localhost', but you can set anything here (IP, domain or path to socket in 'localhost:/path/to/socket' format). Default: localhost

  Example: host = localhost

• user

  Database user account name. In many cases (if you follow this documentation) that will be 'lms'. If you want to use privileged account, you can enter 'root' (MySQL on most of *nixes), 'mysql' (on PLD) or 'postgres' (PostgreSQL). Default: mysql

  Example: user = lms

• password

  Database user password. Default: empty.

  Example: password = password

• database

  Database name. Default: lms

  Example: database = lms

• server_encoding

  Database encoding. Use if your database encoding is not Unicode. Postgres is performing conversion automatically, but if you use MySQL PHP and iconv in LMS DB drivers is used. Default: unicode

  Example: server_encoding = latin2

2.6.2. Section [directories] - Directories Settings

• sys_dir

  System directory. It is a place where the entire content of LMS UI is placed, that means index.php, graphics, templates and the rest. By default index.php tries to guess where is it located using getcwd(), but it's better to say it where it is:

  Example: sys_dir = /var/www/htdocs/lms/

• modules_dir

  Directory with LMS "modules". That is content of /modules directory. By default it is modules subdirectory of sys_dir.

  Example: modules_dir = /usr/share/lms/modules/

• lib_dir

  Directory with LMS "libraries". That is content of /lib directory. By default it is lib subdirectory of sys_dir.

  Example: lib_dir = /usr/share/lms/lib/

• backup_dir

  Directory for database backup files - it's a place where LMS can write its database snapshots. By default it is backups subdirectory of sys_dir.

  Example: backup_dir = /var/backup/lms/

  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/

  If that directory is accessible from WWW level (within Web Server DocumentRoot), anybody can access them without authentication.

• smarty_dir

  Directory with Smarty library - By default Smarty subdirectory of lib_dir.

  Example: smarty_dir = /usr/lib/php/Smarty

• smarty_compile_dir

  Compilation directory for Smarty. It's a place where Smarty compile its templates. By default it is templates_c subdirectory of sys_dir.

  Example: smarty_compile_dir = /var/smarty/compile/lms

• smarty_templates_dir

  Directory with templates for Smarty. By default it is templates subdirectory of sys_dir.

  Example: smarty_templates_dir = /usr/share/lms/templates

2.6.3. Section [finances] - Finances Settings

This section consist options for financial system and for payment forms. You can read more about that in chapter 'Documents'.

• suspension_percentage (optional)

  Percentage for suspended liabilities. Default: '0'

  Example: suspension_percentage = '50'

2.7.1. Idea

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

By default following access rules list is defined:

• full access

• read only (excluding Helpdesk)

• nodes connection/disconnection

• finances management

• configuration reload

• customers management

• nodes management

• stats access

• mailing access

• Helpdesk (RT) administration

• Helpdesk (RT) operation

• accounts management

• configuration

• networks and devices management

• timetable management

• daemon management and configuration

• users edition and addition forbidden

• no access

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:

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.9.1. Invoices

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

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

• header

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

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

• footer

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

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

• default_author

  Invoice issuer name. Default: empty

  Example: default_author = "invoicing expert"

• cplace

  Invoice issue location (city). Default: empty.

  Example: cplace = Warsaw

• print_balance_history

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

  Example: print_balance_history = true

• print_balance_history_limit

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

  Example: print_balance_history_limit = 20000

---

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.

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

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:

2.9.3. Cash Receipts

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
)
?>

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.

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

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

3.3.3. Search

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

3.3.4. Groups

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

3.3.5. New Group

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

3.3.6. Messages

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

3.3.7. Printing

Set of modules to provide printer-friendly version of your records:

• Customer list with filter and sort abilities,

• Liability report for any range of customer(s), for specified date,

• Customer balance for selected period

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

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.

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

3.4.3. Search

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

3.4.4. Messages

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

3.4.5. Printing

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

3.5.1. List

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

3.5.2. New device

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

3.5.3. Map

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

You need GD or Ming library compiled in PHP to be able to use graphical map.

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.

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

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

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

3.7.7. Invoices list

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

3.7.8. New Invoice

Allows you to issue an invoice for selected customer manually.

3.7.9. Cash Receipts List

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

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

3.7.10. New Receipt

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

3.7.11. Import

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

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

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

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

3.7.12. Printing

There are several options for balance sheet printouts:

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

• Total invoiceless income for given period

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

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

• Customer balance sheet for given period.

• Invoices for given period or/and selected customer.

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

3.8.1. Accounts

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

3.8.2. New Account

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

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

3.8.3. Aliases

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

3.8.4. Domains

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

3.8.5. Examples

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

  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:

# smtpd.conf file (Cyrus-SASL):

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

# authpgsqlrc (or authmysqlrc) (Courier):

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

# main.cf (Postfix):

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

# pgsql_virtual_domains_maps.cf (Postfix):

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

# pgsql_virtual_mailbox_maps.cf (Postfix):

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

# pgsql_virtual_alias_maps.cf (Postfix):

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

3.11.1. Filter

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

3.11.2. Compacting

Depending on chosen update frequency amount of database data used for statistics might grow fast, which will lead to extension of time needed to generate statistics. For that reason in 'Compacting' menu you're able to shrink your database size without data loss. This module will compact data using following logic:

• Low precision: data from previous date and older will be approximated to one day. If you save data each 10 minutes 6*24 records will be compacted to one.

• Medium precision: data older than month will be approximated to one day.

• High precision: data older than month will be approximated to one hour.

Data approximation is irreversible.

3.11.3. Printing

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

3.12.1. Queues List

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

3.12.2. New queue

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

3.12.3. Searching

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

3.12.4. New ticket

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

3.13.1. Timetable (Task list)

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

3.13.2. New event

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

3.13.3. Search

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

3.14.1. User Interface

3.14.1.1. Basics

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

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.

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

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

3.14.2. Tax Rates

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

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

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

3.14.3. Number plans

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

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

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

Sequence template might be any string, which consist some of symbols (specifiers) known from PHP strftime function. Detailed information and list of all symbols can be find in PHP Manual. The most important and the only required symbol in sequence template is '%N', which will be substituted with incremented document number. All other symbols will expand to document's date of issue. Below you can find most popular ones:

• %N - integer number, uniquely identifying document

• %[1-9]N - as above, but with leading zeroes, ie. '%4N' will return '0012' for 12

• %Y - year as a 4 digit number

• %y - year as a 2 digit number

• %m - month number with leading zero (01 to 12)

• %b - short month name (according to system locales)

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

3.14.4. Hosts

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

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

3.14.5. Daemon

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

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.

-----------+------------------------------------------------------+---------
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
-----------+------------------------------------------------------+---------

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.2. lms-notify-sms

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

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

• limit

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

  Example: limit = -20

• smstemplate (mandatory)

  Message template. Default: not set.

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

4.3.3. lms-cutoff

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

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

• limit (optional)

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

  Example: limit = -20

• message (optional)

  If not empty, that message will be written to warning message field in customer record after cutting him off. You can use %now variable, and it will be replaced by current date. Default: 'Automatic cutoff caused by exceeding of liabilities limit on %now'

  Example: message = ''

4.3.4. lms-payments

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

This scripts may be configured with two options related to invoices in [payments] section of lms.ini file:

• deadline (optional)

  Payment deadline in days. Default: 14

  Example: deadline = 7

• paytype (optional)

  Type of payment. Default: 'TRANSFER'

  Example: paytype = 'CASH'

• suspension_description (optional)

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

  Example: paytype = '(suspension)'

• comment (optional)

  Description on invoice attached to every periodical assigment

  Default: '%tariff subscription for period %period'

  Some keywords are substitiuted:

  %tariff - subscription name

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

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

  %desc - tariff description

  Example: comment = 'Subscription for %current_month'

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

4.3.5. lms-traffic

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

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

---

4.3.5.1. Installation

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

<IP_address> <n_of_spaces> <upload_bytes> <n_of_spaces> <download_bytes>
<IP_address> <n_of_spaces> <upload_bytes> <n_of_spaces> <download_bytes>
...

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

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/sbin/iptables

• wan_interfaces

  Interface(s) name(s) that should be considered. Default: not defined.

  Example: wan_interfaces = eth0

• local_ports

  List of source/destination ports for packet counting. Default: not defined.

  Example: local_ports = 80

• script_owneruid

  UID of 'outfile' script owner. Default: 0 (root).

  Example: script_owneruid = 0

• script_ownergid

  GID of 'outfile' script owner. Default: 0 (root).

  Example: script_ownergid = 0

• script_permission

  Permissions of 'outfile' script. Default: 700 (rwx------).

  Example: script_permission = 700

4.3.7. lms-makedhcpconf

This module creates DHCP configuration script - dhcpd.conf.

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

• config_file

  Output file location. Default: /etc/dhcpd.conf

  Example: config_file = /tmp/dhcpd.conf

• networks

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

  Example: networks = public-custa public-custb

• customergroups

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

  Example: customergroups = group1 group2

• default_lease_time

  Default lease time. Default: 86400.

  Example: default_lease_time = 43200

• max_lease_time

  Maximal lease time. Default: 86400.

  Example: max_lease_time = 43200

• ignore_ddns

  Dont put 'ddns-update-style none;' on beginning of file. Useful for older (2.2) versions of DHCP. Default: Off.

  Example: ignore_ddns = 1

• log_facility

  Logging options for DHCP daemon. Default is applied if not specified.

  Example: log_facility = 7

• script_owneruid

  UID of 'config_file' config owner. Default: 0 (root).

  Example: script_owneruid = 0

• script_ownergid

  GID of 'config_file' config owner. Default: 0 (root).

  Example: script_ownergid = 0

• script_permission

  Permissions of 'config_file' file. Default: 600 (rwx------).

  Example: script_permission = 700

You can setup leases time on per-host basis by creating [dhcp:network_name] section (in lowercase), eg.

[dhcp:public-custa] # network name, must be lowercase!!!
default_lease_time = 3600
max_lease_time     = 3600

[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/sbin/iptables

• script_file

  Output file with rules. Default: /etc/rc.d/rc.masq

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

• pre_script

  File appended after cleaning existing rules and before adding new. Default: undefined.

  Example: pre_script = /etc/rc.d/rc.masq-pre

• post_script

  File appended after adding rules. Default: undefined.

  Example: post_script = /etc/rc.d/rc.masq-post

• forward_to

  List of networks for which NAT should be set. Possible values: "" - full forward, "any string" - forward off, "net1 net2" - forward active for selected networks. Default: full forward.

  Example: forward_to = public-custa public-custb

• script_owneruid

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

  Example: script_owneruid = 0

• script_ownergid

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

  Example: script_ownergid = 0

• script_permission

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

  Example: script_permission = 700

• snat_address

  SNAT public address. If unset, for hosts with private addresses assigned "-j MASQUERADE" rule will be used. If set "-j SNAT --to 123.123.123.123" (with your IP here) will be used. Only with lms-makeiptables. Default: not set.

  Example: snat_address = 123.123.123.123

• tcp_redirect_ports (udp_redirect_ports)

  List of port forwardings in source_port:dest_port format. Can be used to map ports of your firewalled machines to the ones on your router. Only with lms-makeipchains. Default: not set.

  Example: tcp_redirect_ports = 80:3128 25:25

4.3.9. lms-etherdesc

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

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

• networks

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

  Example: networks = public-custa public-custb

• etherdesc_owneruid

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

  Example: etherdesc_owneruid = 0

• etherdesc_file

  File location. Default: /var/lib/iptraf/ethernet.desc.

  Example: etherdesc_file = /etc/ethernet.desc

• etherdesc_ownergid

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

  Example: etherdesc_ownergid = 0

• etherdesc_permission

  Permissions for the file. Default: 600 (rw-------).

  Example: etherdesc_permission = 600

4.3.10. lms-sendinvoices

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

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

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

• lms_url

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

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

• lms_user

  LMS user login name. Default: empty

  Example: lms_user = admin

• lms_password

  LMS user password. Default: empty

  Example: lms_password = my_secret

• debug_email

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

  Example: debug_email = admin@mynet.pl

• sender_name

  Email sender name. Default: undefined.

  Example: sender_name = ASK MyNet

• sender_email

  Email sender address. Default: undefined.

  Example: sender_email = admin@mynet.pl

• mail_subject

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

  Example: mail_subject = 'New invoice'

• mail_body

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

  Example: mail_body = ''

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

4.3.11. lms-makemacs

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

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

• networks

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

  Example: networks = public-custa public-custb

• customergroups

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

  Example: customergroups = settlement1 settlement2

• iptables_binary

  Location of iptables binary. Default: /sbin/iptables

  Example: iptables_binary = /usr/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/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/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/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

# 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

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/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/

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

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

  You have to provide numerical UID, not username!

• outfile_group

  GID of output file owner. Default: 0

  Example: outfile_group = 0

  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

  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;

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

• default_publ

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

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

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

• network_footer

  Adds line for currently processed network.

  Example: network_footer = ??

• footer_file

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

  Example: footer_file = /etc/lms/myservice_footer

• footer

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

  Example: footer = # End.

• post_exec

  System command that should be executed after saving output file.

  Example: post_exec = killall -HUP mydaemon

5.2.4. Configuration variables

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

Computer templates:

• %IP - IP address

• %PUBIP - second (public) IP address

• %PIN - PIN of customer who owns node

• %ID - ID of computer

• %MAC - MAC address

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

• %OWNER - owner's ID

• %CUSTOMER - owner's lastname and name

• %NAME - computer name, in uppercase

• %name - computer name, in lowercase

• %INFO - computer description

• %PASSWD - node password

• %UPRATE - guaranteed upload rate

• %DOWNRATE - guaranteed download rate

• %UPCEIL - maximum upload rate

• %DOWNCEIL - maximum download rate

• %CLIMIT - limit of concurrent connections

• %PLIMIT - maximum number of packets per second

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

• %NID - network ID where computer belongs

• %NNAME - network name, in uppercase

• %nname - network name, in lowercase

• %NADDR - network address

• %NIFACE - network interface

• %NMASK - network mask

• %NGATE - network gateway IP address

• %NDNS - primary DNS server IP address

• %NDNS2 - secondary DNS server IP address

• %NDOMAIN - domain name of the network

• %NWINS - WINS server IP address

• %NDHCPS - first IP address of dynamic DHCP range

• %NDHCPE - last IP address of dynamic DHCP range

Network templates (for sections relevant to networks only):

• %ID - network ID

• %NAME - network name, in uppercase

• %name - network name, in lowercase

• %ADDR - network IP address

• %IFACE - network interface

• %MASK - network IP mask

• %GATE - network gateway IP address

• %DNS - primary DNS server IP address

• %DNS2 - secondary DNS server IP address

• %DOMAIN - domain name of the network

• %WINS - WINS server IP address for the network

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

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

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;

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)
  --libdir=DIR          location of database libraries (/usr/lib)
  --incdir=DIR          location of database header files (/usr/include)
  --inifile=FILE        configuration file - disables online configuration

# ./configure --with-pgsql --libdir=/usr/pgsql/lib --incdir=/usr/pgsql/include

# make && make install

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

List of instances should contain instance names separated with spaces.

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

Instance configuration, besides config modules params, have to contain the following primary options:

• Name

  Instance name, unique for each daemon (host where daemon is running).

  Example: system

• Priority

  Priority number, which defines instances reload sequence.

  Example: 10

• Module

  Module name (with or without .so extension). If path is not specified daemon will search module in PREFIX/lms/lib directory, where modules are being placed after "make install".

  Example: /usr/lib/system.so

• Crontab

  Module execution time specified in crontab style. All data must be numeric. Following example executes instance each 5 minutes between 8 and 18 hour every day. If crontab is empty, instance will be reloaded only with UI reload. Default: empty.

  Example: */5 8-18 * * *

Configuration changes does not require restarting daemon.

6.1.4. Starting

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

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

6.2.1. Modules list

6.2.2. System

6.2.3. Payments

6.2.4. Notify

6.2.5. Ggnotify

6.2.6. Cutoff

6.2.7. DHCP

6.2.8. Hostfile

6.2.9. Traffic

6.2.10. Tc (HTB)

6.2.11. Dns

6.2.12. Ethers

6.2.13. Oident

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.

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.15. Parser

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.

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

{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.4. Example Scripts

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

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

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

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

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

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

{
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;

7.2.1. LMS users ('users')

7.2.2. Customers ('customers')

7.2.3. Customer groups ('customergroups')

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

7.2.5. Networks ('networks')

7.2.6. Computers and network devices ('nodes')

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

7.2.8. Network connections ('netlinks')

7.2.9. Financial operations ('cash')

7.2.10. Import of financial operations ('cashimport')

7.2.11. Subscription fees ('tariffs')

7.2.12. Custom liabilities ('liabilities')

7.2.13. Solid payments ('payments')

7.2.14. Financial assignments ('assignments')

7.2.15. Tax rates ('taxes')

7.2.16. Documents numbering plans ('numberplans')

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

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

7.2.19. Invoices ('invoicecontents')

7.2.20. Cash Receipts ('receiptcontents')

7.2.21. Accounts ('passwd')

7.2.22. Domains ('domains')

7.2.23. Aliases ('aliases')

7.2.24. History ('timestamps')

7.2.25. Bandwidth consumption statistics ('stats')

7.2.26. Helpdesk - Request Tracking ('rtqueues')

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

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

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

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

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

7.2.32. Timetable - events ('events')

7.2.33. Timetable - assignments ('eventassignments')

7.2.34. Sessions ('sessions')

7.2.35. Hosts ('hosts')

7.2.36. Daemon configuration - instances ('daemoninstances')

7.2.37. Daemon configuration - options ('daemonconfig')

7.2.38. Database information ('dbinfo')

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.

[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.6.1. LMS project related

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

7.6.2. Unicode-related problems

We are switching to Unicode in UI and databases. Right now there are known problems. When you have to use SQL with poor Unicode support, you should use UI converting capabilities. (PHP only? watch out for perl scripts!). In following example (file lms.ini) we have database in LATIN2 (aka ISO-8859-2) format.

[database]
user     = lms
password = lms12354
server_encoding = latin2 ; if DB is not encoded in Unicode 

7.6.3. SQL engine related

• MySQL

  • Database size:

    Following MySQL documentation ("How Big Can MySQL Tables Be?" in chapter "Table size"), MySQL 3.22 is restricted 4GB per table. Since 3.23 restriction is 8 million terabytes (2^63 bytes). It's worth to mention, however, that some systems have filesystem level, usually at 2 or 4 GB.

  • Number of records:

    True informations can be obtained, by issuing (in mysql shell):

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

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

• PostgreSQL

  • Database size:

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

  • Number of records:

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

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.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.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.1. Intro

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

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

8.4.2. Installation

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

redirector_bypass on
redirect_program /path/to/lms-squid

my $configfile = '/etc/lms/lms.ini';

[redirector]
redirect        = http://net-komp.net.pl