LMS - LAN Management System 1.11-git
PrevChapter 4. ScriptsNext

4.3. Description and configuration

4.3.1. lms-notify

lms-notify it's a perfect tool to remind your customers that they are actually the ones who cover all your network and WAN links costs. It makes you possible to create numerous text templates for various occasions and use them for mailing your customers. For SMTP connection Mail::Sender module is used.

4.3.1.1. Templates

You can use following variables in your templates:

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

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

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

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

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

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

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

  • %pin - PIN code of the customer

  • %cid - customer ID

  • %number - document number (invoices, debit notes and deadline notifies only)

  • %value - invoice value (invoices and deadline notifies only)

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

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

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

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

NOTE: This message has been generated automatically.

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

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

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

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

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

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

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

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

Date       | Description                                          | Amount
%last_10_in_a_table

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

4.3.1.2. Configuration

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

  • debtors_template

    Lets you setup message template which will be sent to debted customers. Default: none.

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

  • debtors_subject

    Lets you set subject of message to debtors. Default: 'Debtors notification'.

    Example: debtors_subject = Debt information

  • invoices_template

    The message template which will be sent to customers if new invoice is created (in last 24 hours). Default: none.

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

  • invoices_subject

    Subject of 'invoices' message. Default: 'New invoice notification'.

    Example: invoices_subject = Invoice information

  • notes_template

    The message template which will be sent to customers if new debit note is created (in last 24 hours). Default: none.

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

  • notes_subject

    Subject of 'notes' message. Default: 'New debit note notification'.

    Example: notes_subject = Debit note information

  • deadline_template

    Lets you setup message template which will be sent to debted customers when (not payed) invoice reaches paytime. Default: none.

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

  • deadline_subject

    Subject of 'deadline' message. Default: 'Invoice deadline notification'.

    Example: deadline_subject = Deadline information

  • limit

    Lets you setup limit of customer debt. The message will be sent if customer balance is below that value. Default: limit = 0

    Example: limit = -20

And list of options for mailing only:

  • mailfrom (mandatory)

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

    Example: mailfrom = staff@bigpro.com

  • mailfname

    Sender name. Default: none

    Example: mailfname = Administrators

  • smtp_host

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

    Example: smtp_host = smtp.bigpro.com

  • smtp_auth

    SMTP authorization type. Allowed values: LOGIN, PLAIN, CRAM-MD5, NTLM. Default: none

    Example: smtp_auth = LOGIN

  • smtp_user

    Login for SMTP authorization. Default: none

    Example: smtp_user = admin

  • smtp_pass

    Password for SMTP authorization. Default: none

    Example: smtp_pass = password

  • debug_email (optional)

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

    Example: debug_email = lexx@domain.pl

4.3.2. lms-notify-sms

lms-notify-sms it's a lms-notify equivalent, but it's intended to send reminders via SMS. Actually it supports smstools and gnokii services. Use [sms] section for SMS Service configuration.

Configuration of lms-notify-sms should be set in lms.ini file, [notify-sms] section. Here you can use all lms-notify options plus:

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:

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:

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

4.3.5. lms-traffic

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

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

4.3.5.1. Installation

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

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

Note

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

Next you should install lms-traffic script and your custom script into crontab. Among standard options you can use define location with created data file. 

-f=/file 	location and name of data file, default: /var/log/traffic.log
Warning

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

4.3.6. lms-traffic-logiptables

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

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

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:

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

[dhcp:public-custa] # network name, must be lowercase!!!
default_lease_time = 3600
max_lease_time     = 3600
You can also specify gateway, dns servers, domains name and wins server for individual host by creating [dhcp:ip_address] section, eg. 
[dhcp:213.25.209.216]
domain  = anotherdomain.com
gateway = 213.25.209.251
dns     = 213.25.209.8
wins    = 213.25.209.10

4.3.8. lms-makeiptables, lms-makeipchains

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

Configuration of those scripts should be set in lms.ini file, [iptables] or [ipchains] section. Following parameters are valid:

4.3.9. lms-etherdesc

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

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

4.3.10. lms-sendinvoices

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

This module, unlike the others, needs some extra Perl modules to work: LWP::UserAgent, MIME::QuotedPrint and Mail::Sender.

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

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:

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:

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:

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:

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:

4.3.16. lms-rtparser

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

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

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

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

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

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

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

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

:0 A
$DEFAULT

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

# exim.conf file:

system_filter_pipe_transport = address_pipe

# system_filter.txt file:

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

Note

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

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

PrevHomeNext
List of available scriptsUpConfiguration file generator (lms-mgc)