LMS consist a few modules. LMS-UI is user interface, which is responsible for all interactions with user, entirely written in PHP and it uses SQL database to store all data, thus PHP script interpreter and SQL engine of your choice (MySQL or Postgresql). LMS also contains a set of Perl scripts, responsible for various operations, ie. periodically applying subscription fees or sending reminders to users who are in debt. It also contains LMS-MGC, which may be configured to generate virtually any configuration file or script and manage your server. Note that some of the scripts might need additional Perl modules to function. At the end there is also LMS Daemon, written in C, which is being used (its plugins in fact) as a drop-in replacement for LMS-MGC - to configure and manage (ie. restart) your services. It's main advantage is that it responds for all LMS-UI changes in realtime. Because LMS-UI is written in PHP, it needs Web server to work. Apache is preferred (www.apache.org). Interpreter version should be 5.2.x or higher. PHP can be downloaded from www.php.net. At least following PHP modules needs to be installed (look for "extension" in php.ini or in output of phpinfo function): pcre, posix, zlib (for compressed backups), gd and/or ming (network map only), mysql or mysqli or pgsql (for db support), iconv, mbstring (LMS uses unicode) PEAR::Mail (which require PEAR::Net_SMTP and PEAR::Net_Sockets) for mailing. MySQL server in version 5.x is supported. Probably LMS won't work correctly with older versions. PostgreSQL in version 8.4.x or higher is supported. LMS-UI requires Smarty library (http://www.smarty.net) in version 3.0 or higher. Newer versions of Smarty requires that you have not enabled "magic_quotes_runtime" (set to Off) option in PHP configuration. 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), If you intend to run LMS Daemon you will need working C compiler, because daemon will be provided in source code form only. 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. LMS in tarball (.tar.gz) archive can be downloaded from project home page (www.lms.org.pl), which should be extracted and placed in chosen directory (i.e. /var/www/lms) and made available for Web Server (ie. with Alias /lms/ /var/www/lms): $ cd /var/www $ wget http://www.lms.org.pl/download/stable/lms-x.x.x.tar.gz $ tar zxf lms-x.x.x.tar.gz Smarty library is included in LMS package but if you are using CVS you have to install Smarty yourself. After download copy contents of Smarty's lib directory into /lib/Smarty or use /devel/smarty_install.sh script which will do this for you. Location of all directories can be set in [directories] section in lms.ini configuration file. Configuration files (sample/lms.ini and sample/lms-mgc.ini) should be placed in /etc/lms directory. Scripts from bin directory should be moved to /usr/sbin directory, so you can execute it directly without giving path. Web Server must have read permission on lms.ini file and write permission on backup directory. Please consider security implications: you might want to protect backup directory with .htaccess and place your lms.ini outside Web Server's DocumentRoot (LMS allows you to place it in its home directory, but then it's possible to read it with http://yourserver/lms.ini, and it contains valuable information such as database password!). It's absolutely required for LMS to disable register_globals PHP's option. Recommended setting in php.ini (or httpd.conf for LMS virtual host directory): mbstring.func_overload = 7 register_globals = off max_execution_time = 60 ; or more memory_limit = 32M ; or more Default language of user interface is English, and national characters are encoded in UTF-8. For proper display of national characters in other languages you must define appropriate locales. E.g. for polish language it's achieved by running the following command: # localedef -v -c -i pl_PL -f UTF-8 /usr/share/locale/pl_PL.UTF-8 Instructions about database encoding settings in follow-up of this chapter. That very popular database server is available with majority of Linux distributions. If, however, you have to install it yourself, start with downloading its sources from www.mysql.com. After extracting, go to directory with MySQL and type this sequence of commands: $ ./configure --prefix=/usr/local/mysql $ make $ make install $ /usr/local/mysql/bin/mysql_install_db $ chown mysql -R /usr/local/mysql/var $ /usr/local/mysql/bin/safe_mysqld & $ /usr/local/mysql/bin/mysqladmin -u root password new_password You have to create database if you run LMS for the first time. In order to create database and load it with schema go to LMS directory and run: mysql -u[user name with database creation rights] -p Enter password:[just enter password :)] mysql> CREATE DATABASE lms CHARACTER SET utf8 COLLATE utf8_polish_ci; mysql> GRANT USAGE ON lms.* TO lms@localhost; mysql> GRANT ALL ON lms.* TO lms@localhost IDENTIFIED BY '[your_password]'; mysql> flush privileges; Because MySQL is default database for LMS, configuration is limited to [database] section setup. Thus you need to edit /etc/lms/lms.ini and fill in password and user's name: user = lms password = your_password After this step you should be able to enter your system without any problems. Just write an URL for your LMS installation. If there's no user account (first run), you'll be prompted with form to add username and some personal data. When you enter correct admin personal details LMS will move you to login page, where you can use newly created account. Let's stop here and add some stuff to cron, for peace of mind: 12 4 3,10,17,21,28 * * /usr/bin/mysqldump -u lms --password=your-super-secret-password \ --add-drop-table --add-locks lms > backups/lms-auto-"$(date +%s)".sql That will create mysql database backup automagically each 3, 10, 17, 21 and 28 day of month at 4:12 at night. LMS require PostgreSQL 8.4 or higher. If you have not installed PostgreSQL server, you can compile it yourself from sources available on www.postgresql.org. That is a short version of installation procedure, more info can be found in Postgres documentation. After you download and extract sources go to main directory and run following commands: $ ./configure --enable-locale $ gmake $ su $ gmake install $ adduser postgres $ mkdir /usr/local/pgsql/data $ chown postgres /usr/local/pgsql/data $ su - postgres $ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data --locale=pl_PL.UTF-8 $ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 & Applies to version <= 9.1.x: It's required to add in postgresql.conf: custom_variable_classes = 'lms' While server is running you can start with adding database and its owner, both named 'lms' and loading database schema: $ /usr/local/pgsql/bin/createuser -DPRS lms $ /usr/local/pgsql/bin/createdb -E UNICODE -O lms lms 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/local/pgsql/data/pg_hba.conf (refer to Postgresql documentation). By default password is not required and you can comment it with semicolon. After this step you should be able to enter your system without any problems. Just write an URL for your LMS installation. If there's no user account (first run), you'll be prompted with form to add username and some personal data. When you enter correct admin personal details LMS will move you to login page, where you can use newly created account. Let's stop here and add some stuff to cron, for peace of mind: 12 4 3,10,17,21,28 * * /usr/bin/pg_dump -U lms --clean \ lms --file=backups/lms-auto-"$(date +%s)".sql Main configuration file of LMS is lms.ini, which must be placed in directory /etc/lms or in LMS root directory (not recommended, see !!!). It contains configuration options for LMS-UI and for all scripts with exception of LMS-MGC. Remember to remove semicolons (comments sign) from beginning of line with parameter that you set. As of version 1.6 and later storing config in lms.ini is beeing treaded as obsolete. The only required values there are from [database] and [directories] sections. Other settings are stored in database and could be changed by user interface. type Database driver type. Currently are supported 'mysql' or 'mysqli' and 'postgres'. Default: mysql Example: type = mysql host Host where database is running. Usually 'localhost', but you can set anything here (IP, domain or path to socket in 'localhost:/path/to/socket' format). Default: localhost Example: host = localhost user Database user account name. In many cases (if you follow this documentation) that will be 'lms'. If you want to use privileged account, you can enter 'root' (MySQL on most of *nixes), 'mysql' (on PLD) or 'postgres' (PostgreSQL). Default: mysql Example: user = lms password Database user password. Default: empty. Example: password = password database Database name. Default: lms Example: database = lms 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_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 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' In LMS you may define up to 256 rules to access the system. Each can permit or deny access to defined modules. Each user can have any combination of access rules assigned to his account. By default following access rules list is defined: full access read only (excluding Helpdesk) nodes connection/disconnection finances management configuration reload customers management nodes management traffic stats messaging (email, sms) Helpdesk (RT) administration Helpdesk (RT) operation hosting management configuration networks and devices management timetable management daemon management and configuration cash operations customers groups management nodes groups management customers to groups assignment nodes to groups assignment voip accounts management Userpanel management users edition and addition forbidden no access Most of them grant access to modules and two denies. Modules that user has always access are: welcome, copyrights, logout, chpasswd (chpasswd can change only own password), access to all others is defined by rules. If you don't define any access rule for user, then LMS defines 0 rule for him, which mean: full access. Algorithm that decides whether user has access to given module or not is as following: - First of all: checking list of modules that user always has access. - Next: checking if module match rules in each levels user has access to. - Finally: Decision if user is permitted to access modules. If module match to any level that denies access then access will be forbidden even if user has level that permits access to module. For example, if someone has full access and no access to "add computer" module, then he won't able to access module. If module matches level that permits access to module, then LMS will grant access to module, but if module does not match at any level then no-access-message also will be printed. Advanced users can define any additional access rules or redefine existing ones. In order to do that you must make PHP script based on file lib/accesstable.php. Then set option custom_accesstable in [phpui] section to created file name. In that way it's possible to define your own rules to allow or deny access for any modules. Module is a name of PHP file in modules directory, given without extension in access rules. For example, it's possible to define rule for invoices display (e.g. for lms-sendinvoices script) in the following way: <?php $access['table'][100]['name'] = 'invoices display'; $access['table'][100]['allow_reg'] = '^invoice$'; ?> Since version 1.5.4 LMS was released in polish language only. If you are upgrading read polish documentation for upgrade description. In newest versions upgrade is very easy. That process has two stages. Before you start check LMS requirements (they're changing). Also if you're using MySQL check user privileges, they're changed few times in the past. Now, overwrite old files with new ones and remove contents of templates_c directory (or better create new LMS directory tree). Second stage is a database structure change - it's self-executing process acting upon first login to the UI. If you've got CVS version you've to install Smarty library. Just copy contents of Smarty's /lib directory to /lib/Smarty. It can be done (including Smarty download) automatic with use of /devel/smarty_install.sh script. LMS makes possible to generate and to store various documents i.e. invoices, receipts and non-financial documents i.e. contracts, protocols and others. Documents can be numbered with numbering plans (patterns) defined in menu Configuration - Numbering Plans. Below is presented method used by LMS to calculate tax value. Values of all calculations are rounded to hundredths. Unitary price in LMS database is brutto value (including tax). tax value = (tax rate / 100) + 1 Example: tax rate is 22% tax value = (22 / 100) + 1 = 1.22 unitary netto price = unitary brutto price / tax value Example: unitary brutto price of 1 meter of cable is $2.56, tax rate is 22% unitary netto price = $2.56 / 1,22 = $2.10 total brutto price = unitary brutto price * count Example: unitary brutto price of 1 meter of cable is $2.56, number of meters is 1366, tax rate is 22% total brutto price = $2.56 * 1366 m = $3496.96 total netto price = total brutto price / tax value Example: unitary brutto price of 1 meter of cable is $2.56, number of meters is 1366, tax rate is 22% total netto price = ($2.56 * 1366 m = $3496.96) / 1,22 = $2866.36 It's possible to issue invoices in either automatic or manual way. Manual invoices creation is possible in 'New Invoice' module from 'Finances' menu. Automatic issue might be helpful while you have legal contracts with your users. In this case invoices are created by lms-payments script or lmsd daemon. For proper work of printouts you need to define division's invoices data (e.g. header, footer, default expositor, place, bank account) and configure some options in configuration section [invoices]: print_balance_history If true on invoice (html) will be printed history of financial operations on customer account. Default: not set. Example: print_balance_history = true print_balance_history_limit Records number on customer balance list on invoice. Specify last x records. Default: 10. Example: print_balance_history_limit = 20000 Generated invoices can be viewed in two ways: by clicking on printer icon, in balance sheet page or by clicking 'Invoices List' in 'Finances' menu. In second case, is also possible to filter invoices for printing. When printing by default are displayed original and copy pages, it can be changed: default_printpage Coma-separated list of default invoice printout pages. You can use "original", "copy", "duplicate". Default: "original,copy". Example: default_printpage = "original" 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. It's possible to create invoices as PDF files. Setting option type in [invoices] section to 'pdf' will force invoice being created in PDF instead of html. Option template_file has the same meaning, with one difference, that it might take predefined values: 'standard' - basic invoice (invoice.html equivalent) and 'FT-0100' - invoice adjusted for printing on FT-0100 paper including payment form. You can set template_file option for php file name, but this feature is meant for advanced users as it requires you to create more complicated php file than the one used with html invoices Smarty template. LMS allows for automatic IBAN number generation. As of now it supports fixed lenght of 26 digits and 2 letters (letters are set fixed to PL -- POLAND). You need to specify 8 to 20 digits, the rest is taken as as-many-leading-zeros-as-needed plus Customer-ID Be aware that for example Cyprus and Hungary also use 26 digits. More on: Wikipedia Credit notes uses invoices settings from [invoices] section. Default invoice template include also credit notes contents, but you have possibility to define different template for credit notes (the rest of options is common for both invoices and credit notes): cnote_template_file Credit note template, which should be placed in templates directory. Default: invoice.html. Example: cnote_template_file = invoice-mynet.html Transfer forms it's Polish specific feature. Data for payment form printouts is get from customer's division info. The title of payment can be set using 'pay_title' option in [finances] section. Receipts are printed in html format by default using provided template. We chave one printout template for cash-in and cash-out receipts. In [receipts] section you can also configure: template_file Cash receipt template, which should be placed in templates directory. Default: receipt.html. Example: template_file = /mytemplates/receipt.html content_type Printout content-type. If you enter here 'application/octet-stream' then browser will ask to save file on disk, instead of displaying it. It's useful if you use your own template which generate eg. rtf or xls file. Default: 'text/html' Example: content_type = application/octet-stream attachment_name File name for saving receipt printout. WARNING: Setting attachment_name with default content_type will (in case of MSIE) print document + prompt for save on disk + bonus browser crash (6.0SP1 on WinXP). Default: empty. Example: attachment_name = receipt.xls It's possible to create receipts as PDF files. Setting option type in [receipts] section to 'pdf' will force document being created in PDF instead of html. Option template_file has the same meaning, with one difference, that it might take predefined value: 'standard' - basic receipt (receipt.html equivalent). template_file option can be set to PHP file name, but this feature is meant for advanced users as it requires you to create more complicated PHP script than the one used with html receipts Smarty template. Documents support is not limited to invoices. You might store virtually any documents you want in LMS, such as contracts, protocols, annexes and others. You can assign any number of documents to each customer in 'Customer documents' tab in 'Customer information' panel. Each document should have defined title, type and additionally you might define it's time span (time until when it's valid) and description. Document files are being stored outside of database (which should be kept in mind while doing backups!) in directory defined with doc_dir in [directories] section of config file. Documents can be uploaded to system as prepared files, but also generated from templates with use of defined wizards. Here system gives great configuration possibilities. In directory documents/templates/default you can find default document wizard (template and engine). You can create unlimited number of own documents wizards, which must be placed in documents/templates/ directory. Each wizard must have file info.php with specified structure: <?php $engine = array( 'name' => 'default', // wizard (directory) name, lower case letters and numbers 'engine' => 'default', // engine directory (engine.php) 'template' => 'template.html', // template file (in 'name' directory) 'title' => trans('Default document'), // description for LMS-UI 'content_type' => 'text/html', // output file type 'output' => 'default.html', // output file name 'plugin' => 'plugin', // plugin file name (in 'name' directory) 'post-action' => 'post-action', // action file executed after document addition (in transaction) ) ?> File info.php define wizard and is required. To generate document is needed engine (file with name engine.php). You can create own engine or use other by setting 'engine' variable to appropriate wizard name. So, there is no need to create engine for each new wizard. Is enough to make 'template' template and file info.php. Member plugin specify name of php file used for printing additional fields on document creation form. Plugin can also consist errors handlers for those fields. After document creation will be executed PHP script which name (without extension) should be specified in post-action value.