Frequently Asked Questions - Installation

Useful Starman commands.
Using the perl based Starman webserver is the easiest way to run LedgerSMB locally (and quite possibly for production use as well).

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

pkill -TERM -f "starman master"

Release the port if Starman is terminated

NOTE: try Restart Starman before doing this.

pkill -KILL -f "starman master"
FAQ Category: 

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 on all your company databases. With each of the databases, you can clean up after having run 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.

FAQ Category: 

Yes; there's at least one known (relatively current) story at (written by 'anarcat' on irc)

FAQ Category: 

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/; and
  • find and remove the .pl files that come in LedgerSMB's project root directory and bin/ and LedgerSMB/Scripts/ directories.
FAQ Category: 

The default configuration limits access to the /ledgersmb/ 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.

FAQ Category: 

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

The other is 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 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 The default values here are in the, so please cp

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

FAQ Category: 

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


FAQ Category: 

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

FAQ Category: 

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/ line 61, referer: http://localhost/ledgersmb/

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 -

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.

FAQ Category: 

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.

FAQ Category: 

( is replaced with 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/ line 8.
Compilation failed in require at LedgerSMB/ line 37.
BEGIN failed--compilation aborted at LedgerSMB/ 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/ 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:

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/ line 8." Line 8 in LedgerSMB/ 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" 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/, I received the login page with no error!!

Written by: Joe

FAQ Category: 

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.

FAQ Category: 

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


FAQ Category: 
Operating system: 

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.

FAQ Category: 

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.3.x 1.4.x 1.5 planned
8.4 yes no no
9.0 yes yes no
9.1 yes yes yes
9.2 yes yes yes
9.3 yes yes yes
9.4  yes yes yes

Versions 1.0, 1.1 and 1.2 are not in this table due to the fact that they're past End of Life.

FAQ Category: