FAQ Category: Installation

Upgrading tarball installations

There are two steps to upgrading a LedgerSMB 1.5.x installation to 1.5.y (x smaller than y):

  1. Upgrade the software
  2. Upgrade the company database

The last step has to be executed for each company database that's set up.

Note that all the steps below are prefixed with the 'sudo' command, but these can be executed as 'root' directly as well.

Upgrading the software

This is by far the easiest part. These are the steps to go through, assuming an installation from tarball:

  • Stop the LedgerSMB application server (e.g. Starman)
    $ sudo service starman-ledgersmb stop
  • Back up the old software by moving it out of the way (assuming you installed in /usr/local/ledgersmb):
    $ sudo mv /usr/local/ledgersmb /usr/local/ledgersmb.backup
  • Untar the tarball into /usr/local/ledgersmb:
    $ sudo tar xf ledgersmb-1.5.x.tar.gz --directory /usr/local
  • Copy the configuration file from the old installation:
    $ sudo cp /usr/local/ledgersmb.backup/ledgersmb.conf /usr/local/ledgersmb/
  • Start the LedgerSMB application server again (Starman example given, as before):
    $ sudo service starman-ledgersmb start

Upgrading the company database

After the software has been upgraded, the company database(s) have to be upgraded. When a user logs in on a database which is of a version different from the software that's used to access the database, a "Database version mismatch" error will be generated.

To upgrade the company database from the Web UI, navigate to the setup.pl page (e.g. when you're hosting your LedgerSMB on https://localhost/ and normally log in through https://localhost/login.pl, now you need to navigate to https://localhost/setup.pl). Log into setup.pl with the database admin credentials (the "lsmb_dbadmin" user, if you followed the installation instructions).

After login, setup.pl will show a sccreen with the following at the top:


Logged in as lsmb_dbadmin
LedgerSMB 1.5 db found

By clicking the "Yes" button, the company database upgrade process will be executed.

Repeat this process for all company databases.

Before starting to update to 1.5, the following are differences to be aware of between 1.4 and 1.5:

  • JavaScript in the browser
  • Additional data constraints
  • PSGI / Apache configuration
  • Printed document templates (e.g. invoice templates)
  • Database schema maintenance

See below for explanations of each of these differences.


Important note: before trying to migrate your database to a new version of LedgerSMB, create a backup of the database!

Upgrading from 1.4

The upgrade process for from-tarball installs works the same as the upgrades between 1.4.x and 1.4.y versions (assuming installation in /usr/local/ledgersmb):

  • Stop the server processing LedgerSMB's web requests, by either
    • Stopping Apache (when using a CGI setup -- this is the usual case)
      $ sudo service apache2 stop
      $ sudo /etc/init.d/apache2 stop
    • Stopping Starman (when using PSGI setup)
      $ sudo service starman-ledgersmb stop
  • Move the current software aside:
    $ sudo mv /usr/local/ledgersmb /usr/local/ledgersmb.backup
  • Untar the new software:
    $ sudo tar xf ledgersmb-1.5.x.tar.gz --directory /usr/local

From here, follow the general 1.5 installation instructions.

When done with the installation process, be sure to continue with the company database upgrade instructions.

Upgrading from 1.3

Please follow the instructions for upgrades from 1.4.

Data from 1.3 is migrated to 1.5 by creating a new database schema (new tables) and populating that from the existing 1.3 tables. As 1.4 and 1.5 have added numerous new data integrity constraints, a number of checks have been implemented to validate if a data migration can be successful: pre-migration checks.

Please note that edited data during the pre-migration checks is saved to the original 1.3 database (if you're not running the migration on your backup).

Even if the pre-migration checks succeed, it's happened that the migration still fails. If this is the case with your data, please contact the developers mailing list or the LedgerSMB channel on Matrix.

Upgrading from 1.2

Please follow the instructions for upgrades from 1.4.

Data from 1.2 is migrated to 1.5 by creating a new database schema (new tables) and populating that from the existing 1.2 tables. As 1.3 through 1.5 have added numerous new data integrity constraints, a number of checks have been implemented to validate if a data migration can be successful: pre-migration checks.

Please note that edited data during the pre-migration checks is saved to the original 1.2 database (if you're not running the migration on your backup).

Even if the pre-migration checks succeed, it's happened that the migration still fails. If this is the case with your data, please contact the developers mailing list or the LedgerSMB channel on Matrix.

There's an added complexity to migrations from 1.2 when compared to migrations from 1.3: the user accounts are not migrated. We'd like to address this issue but are unaware of any users currently in need of migrating from 1.2. Please contact the developers mailing list or LedgerSMB channel on Matrix if you experience this problem. We'd like to help and fix our migration code to help any others who still might need this migration.

Upgrading from 1.1 or earlier

There are no direct upgrades from 1.1 or 1.0. Please first upgrade to any version 1.2 through 1.4 before upgrading to 1.5.

Key areas where 1.5 and 1.4 differ

JavaScript in the browser

While JavaScript was mostly optional in all releases prior to 1.5, having it enabled is a hard requirement for the correct operation of LedgerSMB 1.5 and newer.

Additional data constraints

Unlike the 1.3 -> 1.4 upgrade, the upgrade from 1.4 to 1.5 works fully in-place, just as the patch version upgrades within release series. The following constraints have been added and data stored in the database in violation with these constraints may block a successful upgrade:

  • Number of items sold in sales, out of a purchase invoice, may not exceed the total number in the purchase
  • Items in an order are required to exist as parts or services
  • Items in the pricematrix are required to exist as parts or services
  • Make/model details are required to belong to an existing part

PSGI / Apache configuration

The 1.5 release for LedgerSMB doesn't support CGI installation, meaning that the top-level *.pl files have been removed. Instead, LedgerSMB now uses PSGI, a "glue" framework for Perl web applications and their web servers. PSGI allows LedgerSMB to handle requests with much better response times, because the large parts of the application are kept in memory between requests.

To run a PSGI web application, one needs a PSGI compatible web server. The goto PSGI compatible web server is Starman. For production setups exposed to the web, Starman suggests to run behind a so-called reverse proxy.

Apache or Nginx can serve as reverse proxies. Running behind a reverse proxy has two major benefits:

  1. The setup reduces the exposed code footprint to the (highly audited) code of Apache or Nginx
  2. The reverse proxies can handle static content (JavaScript, CSS, images) directly; they do this much more efficiently

In the conf/ directory, there are reverse proxy configuration files for Apache, Nginx and Varnish. There are systemd service configuration files for a ledgersmb starman service as well.

Full installation instructions for the reverse proxy setup can be found elsewhere on this site.

Printed document templates

As of version 1.5, printed document templates are entirely retrieved from the database, including INCLUDEd templates. This differs from 1.4 in the sense that INCLUDEd documents were retrieved from disk while the top-level templates were read from the database. Due to this change in handling, the following changes were required:

  • Inclusion of the letterhead
  • Included files are no longer included with extension

Inclusion of the letterhead

In 1.4, the LETTERHEAD template was included as:

<?lsmb LETTERHEAD ?>

For 1.5, this should be changed to

<?lsmb INCLUDE letterhead ?>

Included files are no longer included with extension

In 1.4, the base check template would be included into "check.tex" as:

  <?lsmb PROCESS check_base.tex ?>

This no longer works in 1.5, due to the fact that the extension isn't supported anymore. The new syntax has become:

  <?lsmb PROCESS check_base ?>

Database schema maintenance

In the 1.4 series, database schema maintenance was done by loading the file sql/modules/Fixes.sql. This process caused a confusing amount of spurious errors and has been replaced by the mechanism in sql/changes/ which separates each schema change out into its own file.

The table below lists the compatibility of LedgerSMB versions with Perl versions. Products for which support has ceased due to End-of-Life date being reached are not listed and should not be used.

PostgreSQL compatibility
PostgreSQL 1.5 1.6 1.7 planned
5.10 yes no no
5.12 yes no no
5.14 yes yes no
5.16 yes yes no
5.18 yes yes yes
5.20 yes yes yes
5.22 yes yes yes
5.24 yes yes yes
5.26 yes yes yes

Versions 1.4 and earlier are not in this table due to the fact that they're past End of Life.

## At the terminal, and from your LedgerSMB directory:
### Start Starman

starman  tools/starman.psgi

Default port is 5000.

starman -l :8080 tools/starman.psgi

Start with 8080 specified as the port.

Note: some documentation specifies the switch


It has been sugggested that this may give performance advantages in a production environment but isn't recommended while developing.
The manpage has more to say on this.

man starman

Based on that we currently would not recommend using --preload-app even on a production server

### While Starman is running

#### Reload Starman

pkill -HUP -f "starman master"

#### Restart Starman {#RestartStarman}

pkill -TERM -f "starman master"

#### Release the port if Starman is terminated
NOTE: try [Restart Starman](#RestartStarman) before doing this.

pkill -KILL -f "starman master"

First of all, you need to backup all your company databases followed by an upgrade of your PostgreSQL installation. There are plenty of places on the web to explain how to do that. The high-level process is to install the two versions in parallel and run the pg_upgradecluster command.

When the technical upgrade has succeeded, however, you're not ready to see the performance improvements promised by the 8.4+ versions of PostgreSQL with respect to the menu-generation. This is because the database doesn't automatically use the new 8.4+ code definitions.

To take advantage of the performance improvements of 8.4+, you'll need to re-run setup.pl on all your company databases. With each of the databases, you can clean up after having run setup.pl: the tablefunc contrib is no longer required, meaning you can

psql -U ledgersmb -d -f /uninstall_tablefunc.sql

On my own database I needed to run the above command three times to make it stop reporting "ERROR: Can't DROP because other objects depend on it." (On each round the number of other errors increased: on each round the number of objects successfully being dropped increased.)

That should do it. You should have a clean 8.4+ PostgreSQL database with LedgerSMB.

Yes; there's at least one known (relatively current) story at https://wiki.koumbit.net/LedgerSmbUpgrade#A1.2.25_to_1.3.18 (written by 'anarcat' on irc)

In general: neither. The advice is to have the full source tree in /opt/ledgersmb/<version>.

Installing the LedgerSMB modules in the standard Perl search path works, but interferes with running different versions side-by-side.

To undo installation in /usr/local:

  • remove /usr/local/share/perl/5.XX.X/LedgerSMB/
  • delete /usr/local/share/perl/5.XX.X/LedgerSMB.pm; and
  • find and remove the .pl files that come in LedgerSMB's project root directory and bin/ and LedgerSMB/Scripts/ directories.

The default configuration limits access to the /ledgersmb/login.pl page to connections from localhost ( only for maximum security.

If you want to allow connections from other locations, it's highly advisable to use encrypted (VPN) connections to access your ledger in order to maintain good security.

Q: This particular merchant runs Windows. I don't think they have a pole display, though I can check. Ideally, it would be great to accommodate, with or without pole display. If it runs better on Linux, going forward I would propose Linux workstations for new merchants.

Ok. Let's first explain what the problems we have to solve are, then discuss the solutions that are bundled.

In general web browsers are engineered so that malicious sites can't access your computer's hardware. In general we don't want to change the browser (for example with an add-on) to make it do this because there might be a capacity for abuse elsewhere. So things like receipt printers, pole displays, cash drawers, and barcode scanners cannot be directly be accessed by the browser. This makes a web-based point of sale rather challenging, but we have solutions to these problems. The solutions though are only tested on Linux. On Windows they will require slight modification and I would recommend some extra testing. Backup/fallback methods are discussed below as well.

What we do instead preferably is to turn the point of sale terminal into a server for the point of sale hardware. Scripts to do this (written in Bash) are in the utils/pos directory of the LedgerSMB installation. the client-side script is pos-hardware-client-startup-script which basically fires up netcat and listens for data to redirect to a hardware port. You probably want to use firewall software to limit this traffic to approved servers. The ports are configurable on both ends. On the LedgerSMB side, see the pos.conf.pl.

The other is directnet.pl which is used to send printable documents over this (and to the POS printer on the other side). This is designed to be a low-latency alternative to using CUPS and the like. It redirects pole display logic usually to a serial port, and the printer logic to a parallel port.

This means you can use any printer that accepts ESC/POS and it will send signals to open the cash drawer (programmable in the pos.conf.pl) if the cash drawer is the kind that plugs into the printer. You can also use a pole display although currently we only have drivers for the LC3000 by Logic Controls. The drivers are really easy to write though. Feel free to ask for help or contribute one.

Barcode scanners and magnetic stripe readers need to come into the computer as keyboard input. Typically this means a keyboard wedge interface for magstripe readers, and either a keyboard interface for a barcode scanner, or a barcode scanner attached to a POS keyboard with a built-in barcode decoder. I have had better luck with the latter in terms of long-term maintenance, but they both work.

On to the pos.conf.pl. The default values here are in the pos.conf.pl.template, so please cp pos.conf.pl.template pos.conf.pl

For the miost part this defines a single variable for storing the information called $pos_config. Keys for this and their significance are:

rem_host: Remote host to send pole display/printer info to. By default this is the remote host. However if you are running X11 applications remotely you may have to change this.

pd_host; Host for the pole display. Defaults to rem_host
pd_port: Port for the pole display. Defaults to 6601
pd_proto: Protocol for pd. Either 'tcp' or 'udp' defaulting to udp.


Same as pd_* above but for printer

rp_cash_open: The code to open the printer. Defaults to those for the Epson U220D iirc, which is binary string of values 27, 112, 0, 25, 250

coa_prefix: prefix for the till amounts. If you have a till '16' and a coa_prefix of 1300, the till account will be 1300.16. This account must exist or you will get errors.

close_cash_accno: Cash account to put closing cash into. Must exist by closing time.

$pos_sources is used to define memo fields for different types of payment. You can customize this as you want.

$pos_source_default is the default for the sources drop down.

curren is the currency
breakdown covers your currency denominations. Used in closing. I dont know if you want to add a 0.5 as 50 cent piece there since those are rare.

till_type is either the 'cashier' meaning the employee id becomes the till number or 'terminal' in which the last octet of the IP address becomes the till number. If you need to customize this handling you can do so underneath the request to stop editing at a certain point.

Advanced options include

source_accno_override used to override cash account handling of various sources (such as gift certs for example)

disable_tables is no longer necessary. But you can use this if you aren't using projects and/or departments. It defaults to disabling everything.

If the directnet approach for printing does not work for you you can comment out the printer definition at the bottom of the pos.conf.pl and set up cups to process and send the file to the workstation to be printed. This adds a few seconds often, however, so where directnet works, it is preferred especially in time-critical point of sale environments.

Q : Brian Wolf
A: Chris Travers
Source: http://permalink.gmane.org/gmane.comp.finance.ledger.smb.user/6290

By Steven Marshall

I found something very interesting. I created a test HTML page containing solely text called testpage.html. I dropped this file in two locations. One in the Apache root directory (/srv/www/htdocs/) and the other in the ledgersmb directory (/user/local/ledgersmb/). I changed ownership of the file to wwwrun:www. I then ran the following tests:

Test 1:
Results: Page loaded almost instantaneously.

Test 2:
Results: Page loaded in about 14 seconds

It seems to be choking on page loads for files that reside in the ledgersmb directory. My ledgersmb-httpd.conf is located in my ledgersmb directory at /usr/local/ledgersmb. I had added my "Include /usr/local/ledgersmb/ledgersmb-httpd.conf" to the bottom of default-server.conf.

I believe I have solved the issue. I am still testing just to make sure, but it appears that my issue was in ledgersmb-httpd.conf. In the section where by default you "Allow from localhost", I had changed to the following adding two additional "Allow from" statements so that I could connect remotely to Ledgersmb:

Order Deny, Allow
Allow from
Allow from localhost
Allow from 192.168.1
Deny from All

It appears that it was struggling with the multiple "Allow from" statements. Based on Apache documentation I believe I should have been able to do it this way, but I decided to change it to the following, using just one "Allow from" statement and separating the addresses with spaces, and my performance issue cleared up. This is what my modified version that works looks like:

Order Deny, Allow
Allow from 192.168.1 localhost
Deny from All

Source: http://archive.ledgersmb.org/ledger-smb-users/msg05639.html

I manage several companies on LedgerSMB, can I login to any of these companies with one user?
Applies to LedgerSMB 1.3.x -->
V. 0.1 - 22. Nov 2011

I have 100 companies though on my system and decide to change my password, wouldn't I have to change it a 100 times (one for each company)? What would be the best approach to setting up a user that could be used on several companies (databases)?

In LedgerSMB all your users are database users in PostgreSQL. All PostgreSQL users do not have access to login with LedgerSMB on each company database(s). LedgerSMB has to give access to each user as an LedgerSMB application user, even if the user have PostgreSQL superuser rights on the database level.

You can add the Postgresql user to be a LedgerSMB application user when you make an new database or after the database is created. If you import the account into all the other databases, the password management is consistent cross the databases. However, you are not guaranteed the same permissions on all databases. You could have one set on one database and another set on another.

Fast route: User get "Manage Users" or "Full Permissons" access to LedgerSMB
Use setup.pl to create company database number 1 with ledgersmbdbadm user.
Add a normal application user in the proses ("Enter User" screen) example: your_100_db_user_name

Use setup.pl to create company database number 2, 3, 4... with ledgersmbadm user (or a special admin user for each db).
Import the normal application user you made in database 1 ("Enter User" screen in setup.pl)
Username: your_100_db_user_name
Password: Do not set a password. Leave it blank
Import : Yes
Fill inn first name, last name and select Country and assign permissions.

You can also add the user to the db later:
System->Admin Users->Add Users
Username: your_100_db_user_name
Password: Only set a password in the firstdb. Leave it blank in db 2, 3, 4..
Import : Yes
Fill inn first name, last name and select Contry and assign permissions.

If you add the users later you have the opions to add only the permissions the user needs to do a spesific task.

Technical solution:
From LedgeSMB use this user to setup the database you create a databaseuser with Superuser priviliges.
CREATE USER ledgersmbdbadm WITH superuser password 'somepassword';

Create a normal user
CREATE USER your_100_db_user_name WITH password 'somepassword';
(normal user with no drop db rights)

When you create the db:
Use setup.pl to make the company database(es). Use the ledgersmbdbadm user to login to create the company database (first screen) and add a new user on the ("Enter User" screen)
Username: your_100_db_user_name
Password: Do not set a password. Leave it blank
Import : Yes
Fill inn first name, last name and select Contry and assign permissions.

You can add the user to the db later:
System->Admin Users->Add Users
Username: your_100_db_user_name
Password: Do not set a password. Leave it blank
Import : Yes
Fill inn first name, last name and select Contry and assign permissions.

If you add the users later you have the opions to add only the permissions the user needs to do a spesific task.

Direct login to correct company, take a look at this:

Compiled from this e-mail treads:
Question from: Steven Marshall
Answer from Håvard Sørli and Chris Travers


Short error:
Math::BigInt: couldn't load specified math lib(s), fallback to Math::BigInt::FastCalc

Full error message:
[Thu Nov 10 22:53:58 2011] [error] [client] Math::BigInt: couldn't load specified math lib(s), fallback to Math::BigInt::FastCalc at /usr/local/share/perl/5.10.1/LedgerSMB/Form.pm line 61, referer: http://localhost/ledgersmb/menu.pl?login=username&menu=1&id=103&open=:

What should you do with this? Nothing or install math libs

From irc:
ehu: you can run without it, just slower.
ehu: but you can install it and rid yourself of the error reported.

Install Math:BigInt:GMP to get rid of the message.

apt-get install libmath-bigint-gmp-perl

Ubuntu 10.4 LTS:
sudo apt-get install libmath-bigint-gmp-perl

RPM (Centos, Redhat...)
perl-Math-BigInt-GMP is available from the rpmforge repository - http://repoforge.org/

From irc:
haso: The setup script do not check for it. ... Should it ?
ehu: well, since you can run without, I don't think so.
ehu: do you?
haso: It could be an informed option.
ehu: well, that's indeed an idea.
ehu: it's in the install file for debian and RH, I think.

When trying to use XeLaTeX, you may get a message like:

! You are attempting to make a LaTeX format from a source file
! That is more than five years old.
! If you enter to scroll past this message then the format
! will be built, but please consider obtaining newer source files
! before continuing to build LaTeX.

! LaTeX source files more than 5 years old!.
l.545 ...aTeX source files more than 5 years old!}

! Emergency stop.
l.545 ...aTeX source files more than 5 years old!}

No pages of output.
Transcript written on xelatex.log.
Error: `xetex -ini -jobname=xelatex -progname=xelatex -etex xelatex.ini' failed

fmtutil: Error! Not all formats have been built successfully.
Visit the log files in directory
for details.

This is a summary of all `failed' messages and warnings:
`xetex -ini -jobname=xelatex -progname=xelatex -etex xelatex.ini' failed

This is confirmed to be a problem on CentOS 6, Scientific Linux 6, Red Hat Enterprise Linux 6, and Fedora Core 13.

You can correct this issue (as root) by:

cd /usr/var/texmf/web2c
xetex -ini -jobname=xelatex -progname=xelatex -etex xelatex.ini

Once you type this you will get the same message, but have the option to press return and generate the file anyway.

(admin.pl is replaced with setup.pl in LedgerSMB v. 1.3.x and upwards)

I am trying to install ledgerSMB on SuSE 11.1 and have followed the INSTALL and README documents to do so, and have also installed all dependencies.

When I get to the following instruction I get some errors.

$ ./Build test

The errors are seen in the last few lines of output following the instruction. I list them below. Note that prior to these last few lines are many lines starting with "BEGIN failed--compilation aborted ..."

Also note the last line "Failed 6/6 test programs. 58/76 subtests failed." Clearly something is wrong here.

BEGIN failed--compilation aborted at LedgerSMB/Sysconfig.pm line 8.
Compilation failed in require at LedgerSMB/Form.pm line 37.
BEGIN failed--compilation aborted at LedgerSMB/Form.pm line 37.
Compilation failed in require at t/99-versioning.t line 8.
BEGIN failed--compilation aborted at t/99-versioning.t line 8.
# Looks like your test died before it could output anything.
Test returned status 255 (wstat 65280, 0xff00)
DIED. FAILED tests 1-9
Failed 9/9 tests, 0.00% okay
Failed Test Stat Wstat Total Fail List of Failed
t/01-load.t 12 3072 30 12 1-3 5 11-12 14 16 20 26-27 29
t/02-number-handling.t 255 65280 ?? ?? ??
t/03-date-handling.t 255 65280 ?? ?? ??
t/10-form.t 255 65280 ?? ?? ??
t/12-menu.t 255 65280 37 74 1-37
t/99-versioning.t 255 65280 9 18 1-9
Failed 6/6 test scripts. 58/76 subtests failed.
Files=6, Tests=76, 1 wallclock secs ( 0.93 cusr + 0.12 csys = 1.05 CPU)
Failed 6/6 test programs. 58/76 subtests failed.

After restarting both postgresql and apache, I tried to go to http://localhost/ledgersmb/admin.pl and received the following error on Firefox:

Server error!

The server encountered an internal error and was unable to complete your request.

Error message:
Premature end of script headers: admin.pl

If you think this is a server error, please contact the webmaster.
Error 500
Mon Nov 2 08:59:41 2009
Apache/2.2.10 (Linux/SUSE)

PROBLEM SOLVED ==> See below for the solution to this installation problem.

The problem was solved with the help of irc.freenode #ledgersmb. Here is how:

The error message says, "BEGIN failed--compilation aborted at LedgerSMB/Sysconfig.pm line 8." Line 8 in LedgerSMB/Sysconfig.pm is "use Config::Std;" This suggests that there was something wrong with Config::Std. Either it was not installed or there was some problems with its installation.

So, I tried reinstalling Config::Std and I received error messages suggesting problems with dependencies that were not reported when I ran "perl Build.PL"

http://search.cpan.org/ allows you to look up modules, such as Config::Std. Once found, there is a "dependencies" link, which lists dependencies, each of which have further dependencies, which have dependencies... . Well, you get the idea. Be patient and follow through noting all the dependency modules and dependent on dependent modules. Download and install each of these. I started installing those with least dependencies themselves.

I then reran "perl Build.PL" and "./Build test" and then restarted Apache and PostgreSQL. Voila! When I went to http://localhost/ledgersmb/admin.pl, I received the login page with no error!!

Written by: Joe

Q: How could I set it up ledgersmb to support SSL connection?

SSL support on Apache is handled by configuring Apache. For having LedgerSMB connect to PostgreSQL using SSL, you can set the PGSSLMODE environment variable to 'require' in the ledgersmb.conf. Note that by default, LedgerSMB will try to connect to PostgreSQL via SSL and fall back to unsecured connections if this is not available.

We highly recommend using SSL for any access to LedgerSMB over the network.

Make sure you have TexLive installed. Older TeTeX was recommended but according to Ubuntu repositories, TexLive is the new package to install.

You can install this with the following command:

apt-get install texlive-latex-extra


Adding support for other database management systems would require that the database logic be coded to the least common denominator. We have decided that we want to eventually allow add-ons in different languages, and thus the database becomes the only point where we can enforce accounting logic consistantly across all parts of the application. Porting and maintaining such logic across database systems is not feasible for this project.

Additionally PostgreSQL is an outstanding RDBMS and we have no desire to move from it.

The table below lists the compatibility of LedgerSMB versions with PostgreSQL versions. Products for which support has ceased due to End-of-Life date being reached are not listed and should not be used.

PostgreSQL compatibility
PostgreSQL 1.5 1.6 1.7 (planned)
9.1 no no no
9.2 no no no
9.3 no no no
9.4  yes yes yes
9.5 yes yes yes
9.6 yes yes yes
10.0 yes yes yes

Versions 1.4 and earlier are not in this table due to the fact that they're past End of Life.

FAQ Category: Localization / Internationalization

The short answer is that TeX doesn't know how to deal with UTF-8 (or rather non-ASCII) characters. XeTeX has been designed to work around these limitations. The easiest way to generate PDFs is to install Xe(La)TeX and use the 'xedemo' templates - these templates have been 'ported' from LaTeX to XeLaTeX.

Distribution specific install instructions listed below.

Debian / Ubuntu 

Install texlive-xetex that includes xelatex

apt-get install texlive-xetex

but you need to patch LaTeX::Driver
Install liblatex-{driver,encode,table}-perl for latex

apt-get install liblatex-{driver,encode,table}-perl

and libmoosex-followpbp-perl for Template::Plugin::Latex

apt-get install libmoosex-followpbp-perlafter that:

apt-get install libtemplate-plugin-latex-perl  (or cpan Template::Plugin::Latex)

LedgerSMB xelatex configuration

Install xelatex and change the LedgerSMB configuration from the menu:
System -> System Defaults -> Templates directory
Change to "xedemo"

Change a path

From the mailing list: (Chris Travers)
Right now, I am open to suggestions on a better approach, as the Template::Latex api's don't seem to work to do this, but I resorted to changing the paths in LaTeX::Driver::Paths directly (find the location with locate LaTeX/Driver/Paths.pm). This file gets written at installation time for the LaTeX::Driver module and so I consider it reasonably editable.

locate LaTeX/Driver/Paths.pm

If locate is not installed you can do:  find /usr . |grep "LaTeX/Driver/Paths.pm"
/usr/share/perl5/LaTeX/Driver/Paths.pm  ( Debian / Ubuntu )

Make a backup copy of  LaTeX/Driver/Paths.pm (you have to have root priviliges to do this or use sudo)

cp /usr/share/perl5/LaTeX/Driver/Paths.pm /usr/share/perl5/LaTeX/Driver/Paths.pm.backup(Change the path to your path for LaTeX/Driver/Paths.pm)

User your text editor to edit LaTeX/Driver/Paths.pm  (you have to have root priviliges to do this or use sudo)

In LaTeX/Driver/Paths.pm change

$program_path{pdflatex} = '/path/to/pdflatex;


$program_path{pdflatex} = '/path/to/xelatex';


This is the error you get, if you do not change:
/usr/share/perl5/LaTeX/Driver/Paths.pm  (Debian path)  :


latex error - pdflatex exited with errors:
l.26 \RequireXeTeX
! Fatal fontspec error: "cannot-use-pdftex"
! The fontspec package requires either XeTeX or LuaTeX to function.
! You must change your typesetting engine to, e.g., "xelatex" or "lualatex"
! instead of plain "latex" or "pdflatex".
! See the fontspec documentation for further information.
! For immediate help type H <return>.
l.38 }


The utf8 character "hack fix"

Before making this change will UTF8 characters appear as squares in the PDF file. To print utf8 characters in pdf files, you must make the following change:

These are the steps:
su root
open /usr/share/perl5/LaTeX/Driver.pm
in your text editor
go to line 174 on Debian Squeeze (6.x) and line 176 on Debian Wheexy (7.x)
you see "write_file( ..." there

".tex", $source


".tex", {binmode=>':utf8'}, $source


Font fix

In order for Verdana to work, install the package ttf-mscorefonts-installer (Debian/Ubuntu)

apt-get install ttf-mscorefonts-installer

In versions 1.3.28 and up, the demo templates no longer depend on Verdana though, but use the non-proprietary Liberation font set, which can be installed using

apt-get install fonts-liberation

Code reference to LedgerSMB

The code for this is LedgerSMB/Template/Latex.pm

The templates use the Template Toolkit scripting language to generate actual content.
Depending on the typesetting language, the files use
* (Xe)LaTeX; or
* plain text
as the typesetting system.

While LaTeX and XeLaTeX are extremely similar, some differences exist, mainly in the area of font selection and document preamble.

Latex cheat sheet - http://www.stdout.org/~winston/latex/&#13;
Latex in 157 minutes - http://tobi.oetiker.ch/lshort/lshort.pdf&#13;

The LATEX Font Catalogue - http://www.tug.dk/FontCatalogue/about.html&#13;
Guide in Norwegian: http://dag.at.ifi.uio.no/latex-links/uiofonts.pdf&#13;


There's a section dedicated to translation. That should help you to get started.
The basic idea is that everything you can learn from the web about translating with gettext applies to LedgerSMB's gettext translation as well, with the note that you should be able to find a recent POT file in the repository next to the source code for the latest development version (trunk) and the latest stable release (1.3).

We don't know enough about the ideosyncracies with your laws to evaluate that. But quite frankly Free Software sometimes poses an issue with local regulation. If you go with LedgerSMB, I'd recommend working with us to detail any shortcomings and get those resolved.

You can help us to make a list over "X country" laws and LedgerSMB shortcomings according your countrys law.

FAQ Category: Contributing

Getting all the development dependencies and a working copy for LedgerSMB can be time consuming and complex. However, using our Docker Compose infrastructure reduces this to four simple steps:

  1. Install Docker
  2. Install Docker Compose
  3. Clone the LedgerSMB repository from GitHub
  4. Clone the LedgerSMB Development Docker repository from GitHub

(And start the infrastructure from the docker compose file.)


The example below works on Debian Stretch:

### Install Docker

$ sudo apt-get install \
     apt-transport-https \
     ca-certificates \
     curl \
     gnupg2 \
$ curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | sudo apt-key add -
$ sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") \
   $(lsb_release -cs) \
$ sudo apt-get update
$ sudo apt-get install docker-ce

### Install Docker Compose

# Check the latest release at https://github.com/docker/compose/releases/ (and replace 1.17.0 with it)
sudo curl -L https://github.com/docker/compose/releases/download/1.17.0/docker-compose-`uname -s`-`uname -m` \
            -o /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose

### (Optionally) Install docker compose bash completion
$ sudo curl -L https://raw.githubusercontent.com/docker/compose/1.17.0/contrib/completion/bash/docker-compose \
            -o /etc/bash_completion.d/docker-compose

### Clone the LedgerSMB repository from GitHub (checks out 'master' branch)
$ git clone https://github.com/ledgersmb/LedgerSMB.git ledgersmb

### Clone the LedgerSMB Development Docker repository from GitHub
$ clone https://github.com/ledgersmb/ledgersmb-dev-docker.git lsmb-dev-docker

### Pull the latest infrastructure from Docker Hub using Docker Compose
$ LSMB_DEV_VERSION=master docker-compose -f ../lsmb-dev-docker/docker-compose.yml pull


At this point you are set up to start developing and testing LedgerSMB; in order to test your changes in a running LedgerSMB instance, run:

$ cd ledgersmb
$ lSMB_DEV_VERSION=master docker-compose -f ../lsmb-dev-docker/docker-compose.yml up -d

This command starts the container infrastructure (using the names "lsmb-master-devel" and "postgres-lsmb-master-devel" for the LedgerSMB and PostgreSQL containers respectively), taking the sources in the current directory (ledgersmb) to run the application.


File permissions

You may run into problems with file permissions if you want to run commands inside the containers which try to modify your local repository. You will need to either recursively set the file ownership to this user in your local tree, assign liberal 0777 (directory) and 0666 (file) permissions or execute the commands inside the container as root.

Example using www-data user, after you fix your file permissions:

docker exec -ti lsmb-master-devel bash
www-data@90451823cb57:/srv/ledgersmb$ make dojo

Example using root inside the container:

docker exec -ti --user=root lsmb-master-devel bash

Cache issues

The container is set up with template caching enabled. This means that you'll need to restart the container after code changes to see them. This is a simple:

$ LSMB_DEV_VERSION=master docker-compose -f ../lsmb-dev-docker/docker-compose.yml restart

Supported versions

At the time of writing (November 2017), the development container infrastructure only supports development of 1.5 and master/1.6 versions of LedgerSMB.


# diff -u "original file" "new edited file" > “diff file”

Submit your patches ( “diff file” through the Sourceforge project tracker. If you are going to do somewhat largish changes, it's best to discuss how to do them on the developers list. That increases chances for acceptance which is in general the best solution for you and the lsmb community.

At least six active committers and many more developers.

The ledger-smb-devel mailing list have 196 subscribers (22. Mai 2012).
Check the github insights page and the mailing lists at https://lists.ledgersmb.org/listinfo/

Community: /following-and-contributing

192 subscribers (1. Nov 2011)

We ask that all IRC members follow the Ubuntu Code of Conduct.

We also ask that you always use a paste site when pasting more than 2-3 lines. Paste sites include:

FAQ Category: Administration

Assuming you have followed the How Do I Backup My Data instructions, you can restore your database as follows...

1) Restore the roles

$ psql -h [database host] -U [database admin user] < [roles backup file]

For example:

$ psql -h localhost -U lsmb_dbadmin < lsmb-roles.sqlc

2) Create a new database to restore into

$ psql -h [database host] -U [database admin user] -c 'CREATE DATABASE [new company name]'

For example:

$ psql -h localhost -U lsmb_dbadmin -c 'CREATE DATABASE newcompany'

3) Restore the company backup into the new database:

$ psql -h [database host] -U [database admin user] [new company name] < [company backup file]

For example:

$ psql -h localhost -U lsmb_dbadmin newcompany < lsmb-db.sqlc

Log in to the the 'setup.pl' administrative interface, using your ledgersmb database admin user (usually "lsmb_dbadmin" or "postgres"). The default address for setup.pl is http://localhost/ledgersmb/setup.pl.

There are 2 buttons:

  • Backup database (parts, customers, accounting records, etc)
  • Backup roles (your login accounts and rights)

One creates a backup of the content of your database. The other creates a backup of the roles.

Roles are elements which are required to exist before creation of a database, and assign fine-grained access control.

Both files are needed when restoring, and you need to restore the roles before the database.

The backup can be mailed to an e-mail account, or you can download it with your browser, depending on your output selection in the backup screen.

After backing-up the data, it is prudent to confirm that the backups are of non-zero size to confirm that they have been correctly downloaded.

See How Do I Restore My Data for further information.

[work in progess...]
The PDF and PS invoices are generated using a program called LaTeX which handles the layout and typesetting. The actual LaTeX files are creating using Template Toolkit with extensions for LaTeX. These extensions are in the Template::Latex package available from CPAN. The software then generates a LaTeX file which is then processed to create a PDF or PS.

Typically the first thing to do is to install a LaTeX distribution like TexLive (distributed with many Linux distributions and available for OSX and Windows). This provides LaTeX and many of the modules needed. In general I recommend that if your distro has a texlive-extras package that you install this too.

After this is installed, you must then install Template::Latex. This can be done by typing on the command line:

Note: Debian & Ubuntu look below.

cpan Template::Latex

This will also install a number of dependencies including LaTeX::Driver, which will need to know where your LaTeX binaries are. It is usually pretty good at finding them.

If things go wrong and you can't get it to work, the following commands may provide useful diagnostic information when requesting help:

>From the LedgerSMB application directory:
perl -MLedgerSMB::Template::Latex -e print

>From the doc/manual directory in the LedgerSMB application directory:
pdflatex LedgerSMB-manual

Debian & Ubuntu note:
Template::Latex is included in Template::Plugin::Latex which is now in Debian as
libtemplate-plugin-latex-perl. (It has migrated to Debian Testing ('wheezy')).
Install with apt-get install libtemplate-plugin-latex-perl

Ref: Latex in templates & Debian squeeze and xelatex

How the LaTeX templates work
http://permalink.gmane.org/gmane.comp.finance.ledger.smb.user/6347 &#13;

With answers from Chris Travers, Robert James Clay

I had created a second database. To delete it, do I just drop the database from postgresql?

On a GNU-ish *nix platform use the script:
it'll remove the roles and the database.

Copy db :
In psql or your sql client:

Note this will clone everything.
If you want to get rid of the transactions, you will need to delete everything in the acc_trans, ar, ap, and gl tables.

Also if goods and services are used, delete from invoice and inventory as well, and if wishing to clear out all orders, delete from
orderitems and oe.

Sql ledger has the option to add a barcode to a part.

In 1.4, you will be able to add a barcode per make/model record.

How are barcodes added when using LedgerSMB?

Sort term solution:
It's not optimal for a UPC management but it solves the immediate problem:

Add a space separated list with the barcodes to the partnumber field

The partnumber is the "Number" filed on the same line as "Description" in the "Add Part" page.
And yes, "space separated list" works in the POS interface. (If you scan one of the codes in the space separated list )

Here's how the partnumber and description fields work
It searches for any substring match for the entry.
If there is only one match it populates and moves on
If there are no matches it asks you if you want to create one
If there are multiple matches it gives you a list to choose from
same on the invoice screens

Long term solution:
- add a UPC field to the makemodel table.

Question from: Tau (2009)

No: Our templates are in LaTeX or HTML (your choice), and use TemplateToolkit for variable interpolation. No xslt, no xsssl, no programming language other than TT directives......


I have successfully installed LegerSMB and logged in. However, no matter the type of user (i.e. administrator, supervisor or user) the access control of them is always the same. I cannot amend the user access control rights. Therefore many functions such as amending the chart of account are not working. Are there any error on my installation?
[Chris Travers : the Role field in 1.2 affects some aspects of reports but not much more than that. use the check boxes to show/hide menu items. In 1.3, the roles are significantly different.]

In 1.3.x :
Go to the System -> Admin Users -> Search users page, click "Search" and select "[edit]" for the user you're trying to change.

You'll be presented with a long list of authorizations that can be assigned to the user.

There are a number of possible causes for login problems. Some of the more common causes are:

Login in 1.3.x is new. Take a look at this screen guide:

Magic Characters in passwords:
The legacy code from SQL-Ledger has some issues with parsing passwords that contain either the equals sign ("=") or the ampersand (&). This is gradually being resolved in the LedgerSMB codebase but for now avoid using either of these characters in your passwords. The issue is that the equals and ampersand characters are used as delimiters in query strings and posted content - this is being worked on so should not be an issue "soon".

Googlebait: Symptoms of this include "Error! Cannot connect to datasource" and "no database driver specified and DBI_DSN env var not set at LedgerSMB/Form.pm" (suspect this is for admin password).

Browser plugin
The noscript Firefox plugin can prevent the Super-user login and Password box from being created. Disable noscript on your login page.

Password "popup"
Installed in a fresh install of Ubuntu. All seemed fine on in the evening when I went home for the weekend. (I was able to login) Now when I login I get an other password request popup opening with: A username and password are being requested by The site says: "LedgerSMB"

The likely issue here is that the initial password creation temporarily valid, with the idea that the individual setting the password may not be the application user. Consequently the password has expired and you cannot log in.

To solve the Password "popup", you can do one of a couple things:
By: Chris Travers

1) You can locate your pg_hba.conf file and change the authentication type to "trust" briefly while logging in and changing your password. This requires telling PostgreSQL to reload its files (or restarting PostgreSQL)

2) You can log into PostgreSQL with something like: sudo -u postgres psql and then change the expiration date. (on Centos or Red Hat su to the postgres user and run psql: su - postgres) Something like:

ALTER USER 'myusername' WITH VALID UNTIL '2011-11-09';

Then when you log in, you should be able to change your password under the preferences screen or if it will expire within a week, it should pop up that screen when you log in, with a warning on top.

PostgreSQL authorization settings (pg_hba.conf)
Read the "pg_hba.conf settings for production"

The PostgreSQL doc about client authentication and pg_hba.conf

FAQ Category: Integration

REST -- we are working on it. (1. Nov 2011) Check developer mailing list and latest code.
Other language independent API--- we have it for the new code in the form of discoverable SQL interfaces, and are working on rewriting the rest with that in mind

Depends what your online store produces.
We're currently ( 1st Nov 2011) working on creating web service API's but freelock (a frequent visitor of the IRC channel) is already doing it. He doesn't mind sharing his code.

Web service API's discussion is ongoing on the development mailing list. Join and contribute

From the users mailinglist (2011.05.22):
Nigel Titley has an operational bridge working between Oscommerce and
LedgerSMB. He is happy to throw into the pot, especially once the
Ledgersmb RESTful interface comes out of the woodwork. It transfers new orders, new parts and new customers across from OSCommerce to LedgerSMB, handling multiple currencies and it updates the OSCommerce inventory from LedgerSMB. It runs as a regular cron job.

From the users mailinglist (2012.03.07):
LSMB integration with e-commerce?

The faq: REST API or other language-independent interface ?

FAQ Category: Accounting

What you need to do is look for rows in payment_links which have type=0

Then, in acc_trans, you need to identify those rows which have an entry_id of a row which has a 0 amount. That row is probably an fx_transaction row.

The preceding entry_id row is likely one for the same transaction, with a non-zero, non-fx_transaction amount.

You need to insert a new row into the payment_links table with:

  • payment_id: same as for the fx_transaction
  • entry_id: entry_id of preceeding entry in acc_trans
  • type: 0

When you do that, the customer balances should be fixed.

If you find yourself in this situation, the answer is to create a 0 (null) payment: Select both the voiding and the voided invoice in the Cash->Payment (or Cash->Receipt) screen. This will clear the invoices against each other with a net-zero result.

Unfortunately, the LedgerSMB 1.3 version doesn't automatically clear a voiding invoice against a voided invoice upon posting of the former. The workflow described works around this issue.

I have made a payment to a vendor, but entered an incorrect date, far in
the future. Consequently the payment does not show when I try to reconcile
the relevant bank statement.

How do I back-out the incorrectly entered payment?

Cash/Vouchers/Reverse Payment.

Then when you are done adding the payments you want to reverse,
approve the batch.

Tested on: LedgerSMB 1.3.15.
source: http://permalink.gmane.org/gmane.comp.finance.ledger.smb.user/6087

When I open a screen to enter a GL transaction, there is no list to select accounts from. How do I know which accounts are available?

These are AJAX-completed boxes. Just wait after starting to type the account number or the beginning of the account name and a list of items to select from will pop up.

Short answer: Yes

LedgerSMB can tie product sales to a tax class so that VAT can automatically be split off into the required VAT accounts on a sale, and when cancelling an invoice, automatically perform the reverse bookings.

Each product can be 'attached' to an account and the associated % will be applied automatically.

Quite a few users find some of the terminology and accounting processes a little confusing at first. Some of the more popular small business accounting packages tend to hide these aspects of book-keeping from users for simplicity, so with the current user interface there is often some new ideas to grasp.

First step is the manual - the LedgerSMB manual is free and highly recommended reading.

If you would like some background on general accounting practices, there is an (unassociated) tutorial So, you want to learn Bookkeeping" which seems a good place to start.

Another excellent resource is second-hand book stores. Lots of MBA studends sell off their textbooks (presumably to finance their first business rather than pay of gambling debts) so second-hand bookstores will often have very good texts on accounting at bargain prices - these can make great reference books.

Finally it would be remiss not to recommend securing the services of an accountant to help you out with the finer points from time to time, should you feel the need or have a legal obligation to do so.

Wikipedia articles:

FAQ Category: Support

Bug reports can be submitted and viewed at GitHub LedgerSMB Issues

Before raising a bug please check that it doesn't already exist.

It can be useful to discuss potential bugs on the Mailing List or IRC channel before raising them incase there is a known solution

Active support

Versions 1.5 and higher are under active development and are supported by the community.

End of life

If you're looking for help on how to use EOL-ed versions, please try mailing the users mailing list.
If you're looking for someone to create bugfixes, please check with one of the parties providing commercial support or for less urgent fixes LedgerSMB Issues

Version 1.4 has been declared end-fo-life on 2017-09-16. The last release in the series is 1.4.42. No further releases will be made by the community.

Version 1.3 has been declared end-of-life on 2015-12-23. The last release in the series is 1.3.47. No further releases will be made by the community.

LedgerSMB versions 1.0, 1.1 and 1.2 won't be maintained any further due to the fact that there are some known security issues which can't be fixed.

Is there a place where we could buy some consulting for LedgerSMB?
or a minimal setup according to our specs?

Take a look at Commercial Support