Welcome to the LedgerSMB Forums - Open Source accounting software

A text version of this is available

Combined Installation Instructions:

Note: Some of these files have been edited.

README from /ledgersmb/doc/README with LSMB 1.2.18
FAQ from /ledgersmb/doc/faq.html with LSMB 1.2.18
INSTALL from /ledgersmb/INSTALL with LSMB 1.2.18
README.OpenBSD from /ledgersmb/README.OpenBSD with LSMB 1.2.18
README.debian from /ledgersmb/README.debian with LSMB 1.2.18
README.debian from Debian pkg (Note: I have not checked this as of this update May 25, 2009)

LedgerSMB Small Medium Business Accounting
Version 1.2.18

DESCRIPTION:

LedgerSMB is a double-entry accounting system written in perl. It has been tested with PostgreSQL, Apache, Netscape, Mozilla, Galeon,
Explorer, Links, Lynx, Konqueror, Voyager, W3M and Opera clients on Linux, FreeBSD, Solaris, Windows, Mac computers and PDA's.

Data is stored in a PostgreSQL database server, either locally or remote, the display is through a text or GUI web browser.
The system is linked by a chart of accounts. All transactions for AR, AP and GL are stored in a transaction table.
Hyper-links from the chart of accounts let you view transactions posted through AR, AP and GL.

Configuration files let you specify to which SQL database server to connect to,
personal preferences such as company name, language, number and date format, etc.

With the admin script you can create, edit or delete users, create and delete datasets and set up the Chart of Accounts and templates needed for the system.

You can have a group of users using the same dataset and templates for generating Invoices, Income Statements and Balance Sheets or a different set altogether.

Templates are supplied in html, text and tex format to generate most of the forms. Forms can be printed to screen, sent to a printer or e-mailed.

COPYRIGHT:

Licensed under the terms of the GPL.

LATEST VERSION:

Available from www.ledgersmb.org

PLATFORMS:

Non-specific, see requirements.

REQUIREMENTS:

Perl, 5.8.1+
http server (Apache, NCSA, httpi, thttpd, ...)
SQL Server (PostgreSQL 8.0+)
DBD (DBD-Pg)
DBI
Locale::Maketext::Lexicon 0.56+
LaTeX (optional)

FOREIGN LANGUAGE SUPPORT:

28 languages are supported. Language files are ordinary text files, no special software is needed to change or add new translations.

Some of the translation files are not 100% complete. If strings are missing, English is used instead.

INSTALLATION INSTRUCTIONS:

DISTRO AND OS-SPECIFIC NOTES

OpenBSD users:

Please see this document which describes all the steps needed to install LedgerSMB for OpenBSD.
OpenBSD Install

Ubuntu Server users:

Please see this document which describes all the steps needed to install LedgerSMB for Ubuntu Server.
Ubuntu Server 9.04 Install

For Unix systems: '$' signifies the bash prompt, '=>' the psql prompt.

Debian users:

Installation Notes Appendix for Debian
In the dists/deb directory, there files which provide information on which prerequisites can be installed via apt-get and which ones need to be installed via CPAN.

A simple way to do this is to:

apt-get install `cat required_debs.txt`
cpan
> install Class::Std
> install Config::Std

LedgerSMB for Debian

LedgerSMB can be accessed at http://127.0.0.1/ledgersmb, although initial set up is required.

To prepare LedgerSMB for use:

As the postgres user, create a database user for LedgerSMB authentication

$ createuser --no-superuser --createdb --no-createrole -U postgres --pwprompt --encrypted ledgersmb

Here it will prompt twice for the ledgersmb postgres user password, remember what you enter here for step 5.
Create postgres database for ledgersmb

$ createdb -U ledgersmb -O ledgersmb -E UNICODE ledgersmb
$ createlang plpgsql -U postgres ledgersmb
Add databases for all datasets which you want to have available
For instance, we want a dataset for each of examplecom, exampleorg and examplenet, so...

$ createdb -T ledgersmb examplecom
$ createdb -T ledgersmb exampleorg
$ createdb -T ledgersmb examplenet
Populate the user database and set an admin password (this admin password will be used to log into the administrative interface).

$ psql -U ledgersmb -d ledgersmb -f /usr/share/ledgersmb/sql/Pg-central.sql
$ psql -U ledgersmb -d ledgersmb

ledgersmb=> UPDATE users_conf SET password = md5('admin-password) WHERE id = 1;
Edit /etc/ledgersmb/ledgersmb.conf

Scroll down to the very bottom and check your database settings, they will need to be changed. Insert the ledgersmb postgres user password you used in step 1.
Edit /etc/postgresql/8.x/main/pg_hba.conf so that ledgersmb user may connect. Depending on your security infrastructure you can use the METHOD md5 or trust.

Reload postgres so your changes take effect.
Configure apache2

Check /etc/ledgersmb/ledgersmb-httpd.conf and see if it is what you want - it will usually be fine just the way it is.

The default configuration will make this accessible to everyone who can get to your ip address on port 80. If you want to lock it down to localhost, do so now in the forementioned configuration file!

$ cd /etc/apache2/conf.d/
$ ln -s ../../ledgersmb/ledgersmb-httpd.conf
Reload apache2

$ /etc/init.d/apache2 reload

At this point you can connect to http://127.0.0.1/ledgersmb/admin.pl and login with the password set in step 4.

If upgrading from LedgerSMB < 1.2.0-rc5, you need to edit /etc/ledgersmb/ledgersmb.conf to adjust your configuration to match the new options and renaming.

If upgrading from LedgerSMB < 1.2.0-beta1 or from SQL-Ledger, read UPGRADE. The config format, locale names, database schema, and per-user configuration locations have been sufficiently changed with 1.2.0-beta1 so as to require special attention in upgrading.

-- Elizabeth Krumbach <lyz@princessleia.com> Tue, 6 Jan 2009 05:38:48 -0500

Installing LedgerSMB 1.2

This document contains information on how to install LedgerSMB. We recommend that the reader start by reading the section on manual installation and then start by trying the automated means mentioned later.

Also this document assumes that the reader is already familiar with the release notes. If you have not already done so, please read the release_notes file in the doc/ directory.

MANUAL INSTALL

Untar in desired location (for example, /usr/local/ledgersmb, refered to as LEDGERPATH for the remainder of this INSTALL file).
LedgerSMB files should be owned by the apache user, apache:apache on many, but not all, systems.
Create a postgresql admin database role (user), by convention named 'ledgersmb':

$ createuser --no-superuser --createdb --no-createrole -U postgres --pwprompt --encrypted ledgersmb

The prompted password (referred to as ledgersmb-user-password) will later be used in the DBConnect: string in the configuration file 'ledgersmb.conf'

If you prefer to work in postgresql's psql console, the equivalent SQL statement to create the ledgersmb role is:

=> CREATE ROLE ledgersmb LOGIN PASSWORD 'ledgersmb-user-password' NOINHERIT CREATEDB;

Further commands and database interaction should be conducted using the new LedgerSMB admin role 'ledgersmb'.
Create a central user database, owned by the LedgerSMB admin role, 'ledgersmb':

$ createdb -U ledgersmb -O ledgersmb ledgersmb

The equivalent SQL statement is:

=> CREATE DATABASE ledgersmb WITH ENCODING='SQL_ASCII' OWNER=ledgersmb;
On the database that will store your user and session information, run the included Pg-central.sql SQL commands to configure the user and session tables and functions:

$ psql -U ledgersmb -d ledgersmb -f LEDGERPATH/sql/Pg-central.sql

(LEDGERPATH is in the location you expanded the release tarball file. If you untarred in '/usr/local' then LEDGERPATH will be '/usr/local/ledgersmb').

NOTE: LedgerSMB's preferred configuration is to store the user and session management tables in a separate database from the company databases (aka 'datasets', created in admin.pl). If you are already working with or prefer to have your user and session tables in one company dataset, see further information in the manual. You must have PLPGSQL installed in the dataset as well. However that is beyond the scope of these instructions.
The SQL commands in step 4) created an LedgerSMB-managed admin user, e.g. a row in the users and users_conf table. You must now update the 'admin' user's password in users_conf from the default password.

$ psql -U ledgersmb -d ledgersmb

ledgersmb=> UPDATE users_conf SET password = md5('ledgersmb-user-password') WHERE id = 1;

(Change ledgersmb-password to your preferred administrative password, which is separate, but can be the same spelling as postgres-password).

ledgersmb=> \q
Edit the LEDGERPATH/ledgersmb.conf file:
- Copy 'ledgersmb.conf.default' to 'ledgersmb.conf'
  
  $ cp ledgersmb.conf.default ledgersmb.conf
- Make sure to set the section under [globaldb] to point to the central user and session database, using password ledgersmb-user-password:
  
  [globaldb]
  DBname = ledgersmb
  DBhost = localhost
  DBport = 5432
  DBUserName = ledgersmb
  DBPassword = ledgersmb-user-password
Add configuration to Apache:

$ sh configure_apache.sh
Check Dependencies:

The Build.PL script can be used to test for unmet dependencies and run other tests. It doesn't install anything yet, but it will tell you what you are missing. To check for dependencies, run:

$ perl Build.PL

Missing dependencies can generally be installed via a Linux distribution's package manager, or by CPAN. (Build.PL itself uses Module::Build, which is available in packages like perl-Module-Build or libmodule-build-perl.)

Once this is done and dependencies are satisfied, you can check to see whether the installation nominally works by running:

$ ./Build test

The test suites currently check to make sure all the perl modules load and that a number of numeric tests are passed.

Dependencies which are recommended are needed only for specific functionality and may not be required in all circumstances. These include:

* Net::TCLink for credit card processing in a POS environment

* Parse::RecDescent for the CLI script host
Restart Apache (instructions vary with your Linux distro or operating system).

Create Datasets and Users

Create Datasets:

Browse to:  http://'insert-your-hostname'/ledgersmb/admin.pl

login with 'ledgersmb-password'

Select Pg Database Administration Button
Create dataset(s) with:

User: ledgersmb   Password: ledgersmb-password

Superuser: postgres   Password: (postgres-password)

Create one dataset (a PostgreSQL database) for each separate company which will use LedgerSMB for accounting, e.g.:

Ledgeracme or ledgerbigco or smalltoysguy, etc.
Create User(s) pointing to specific datasets (companies) from above:

Browse to: http://'insert-your-hostname'/ledgersmb/admin.pl

login with 'ledgersmb-password'

Select Add User Button
Create user(s) pointing to a specific dataset (ledgeracme, etc.), each with their own password 'user-password', with database login information:

User: ledgersmb
Password: ledgersmb-password

User: johndoe
Password: user-johndoe-password

Congratulations, you have installed and configured LedgerSMB 1.2.*

Load the Accounting Program

Browse to: http://'insert-your-hostname'/ledgersmb/login.pl

Enter a User Name and Password (This time you won't be using postgres or ledgersmb, but one of the created users.)

User: johndoe
Password: user-johndoe-password

Good Luck!! Enjoy!!

FTP INSTALLATION

If you control the server and have shell access, the instructions above are preferred over those given here. instead of those given here. This is simply a set of notes for those who must install on a shared server.

If you do not have access to the server's configuration files install LedgerSMB in userspace by ftp'ing all the files to your server.

Untar ledgersmb in your private_html directory.
turn on script execution for the folder ledgersmb. You can control this with an .htaccess file:

Options +ExecCGI
DirectoryIndex login.pl
Protect the users directory with an .htpasswd file:

order allow,deny
deny from all
Protect the templates directory with an .htpasswd file:

order allow,deny
deny from all
Set up your PostgreSQL database and the tables. The procedure is specified above.

You will most likely only have access to PostgreSQL with some other tools like pgadmin.

OTHER ISSUES:

Before submitting a bug, please consult the COMPATABILITY list. This documents which versions of software have known interoperability problems with LedgerSMB.

SET UP A USER:

Load your web browser and connect to http://'insert-your-hostname'/ledgersmb/admin.pl
Click on "Add User". In the Database section select the driver and enter the user you used to create the dataset.

LOAD THE ACCOUNTING PROGRAM:

Load your web browser and connect to http://'insert-your-hostname'/ledgersmb/login.pl

INSTALLATION CHECKLIST:

Untar LedgerSMB somewhere (i.e /usr/local, /opt)
Change permission for the users, templates, css and spool directory
Edit httpd.conf
Edit ledgersmb.conf
Add the database user ledgersmb
Load admin.pl
Create datasets for companies
Add users

In the Database section enter

a) PostgreSQL

Host:  for local connections leave blank
Dataset:  the dataset created in step 7
Port:  for local connections leave blank
User:  ledgersmb
Password:  'ledgersmb-user-password'

IF SOMETHING DOESN'T WORK:

IRC Support
For real-time help try IRC - you will usually find most of the core team hanging out at irc.freenode.net / #ledgersmb
There are also several mailing lists at http://www.ledgersmb.org where you can seek free help.
For commercial support see http://www.ledgersmb.org/

TROUBLESHOOTING

Error: Access Denied in admin.pl

Likely causes:

The password entered may not match the password set in Manual Install, step 5. You can repreat that step as often as you need to get login to admin.pl working, but in case your 'admin' user is not id=1, try using the expanded version of the SQL:

ledgersmb==> UPDATE users_conf SET password=md5('ledgersmb-user-password') WHERE id = (SELECT id FROM user WHERE username = 'admin');

(Substitute 'ledgersmb-user-password' for your chosen password).
The central database may have been created with a different postgres user (role) than you are using for the connection. In this case, you may not have permission to access the required database entities.
To correct this, assuming that the admin database role is ledgersmb,
issue the following commands from psql:

ledgersmb==> GRANT ALL ON users TO ledgersmb;
ledgersmb==> GRANT ALL ON users_id_seq TO ledgersmb;
ledgersmb==> GRANT ALL ON users_conf TO ledgersmb;
ledgersmb==> GRANT ALL ON session TO ledgersmb;
ledgersmb==> GRANT ALL ON session_session_id_seq TO ledgersmb;

Error: "No GlobalDBH Configured or Could not Connect"

LedgerSMB 1.2 uses a dedicated connection to the central database for user authentication. When the attempt to connect to that database fails, the error message above is displayed. In this case, check the following parameters under the [globaldbh] of the ledgersmb.conf file.

DBUserName should match the database user you imported Pg-central as (if you followed the instructions above, that would be ledgersmb).
DBPassword needs to match the database password to used to connect to.

You can test the above causes by running (from the command line):

$ psql -U [DBUserName]
password: [DBPassword]

When you enter the password, it will not show up on the screen.
The other line that you should pay attention to is the DBConnect line. Parameters in the form of name=value need to match those for your host. The following parameters need to be set correctly in that line:
dbname=ledgersmb (the database you imported Pg-Central.sql into).
host=localhost (don't change unless you know what you are doing!)
port=5432 (don't change unless you know what you are doing!)

The full line should then be something like:
DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432

And that section of ledgersmb.conf looks like:

[globaldb]
DBname = ledgersmb
DBhost = localhost
DBport = 5432
DBUserName = ledgersmb
DBPassword = ledgersmb-user-password

FAQ (Frequently Asked Questions)

Printing to a Printer from a Windows Server

There are several obstacles to printing from a web appliction that was written for Linux or UNIX in Windows. These include:
- Lack of Postscript support in the printing subsystem. To resolve this, you must install Ghostscript and Gsview. The latter package provides a utility called gsprint that will allow you to print Postscript on your Windows printer.
- The fact that most Windows software, including gsprint, tends to print output that will cause the web server to crash. The winprint.bat included with this distribution corrects this problem. To use the winprint.bat solution, configure your printers in your ledger-smb.conf as "winprint.bat printer-name." If you omit the printer name, the default printer will be used.
- Windows does not allow you to set up system printers that all users can access. Thus the web server often doesn't have access to the printers you have set up. To correct this issue, follow the steps at http://support.microsoft.com/kb/q184291/.
Error on converting from SQL-Ledger: ERROR: column "chart_id" contains null values

SQL-Ledger does not enforce a NOT NULL constraint on the chart_id field in the acc_trans table. Consequently, it is possible in certain circumstances to insert transactions into the database with invalid information including NULL chart_id's. When this occurs, normally the Chart of Accounts and Trial Balance will fail to balance. So this is a serious problem with data integrity. LedgerSMB prevents this by adding the NOT NULL constraing but this can cause prevent people from migrating when they have invalid data in their databases.

If you encounter an error like this, the first thing to do is seek technical support, regardless of whether or not you wish to continue the migration. In general the providers of support for LedgerSMB and SQL-Ledger should all be able to be of some assistance. Unfortunately, since this problem involves information loss, no solution can be automated without invalidating your accounting information.
SELinux
http://docs.fedoraproject.org/selinux-faq-fc3/index.html
modify /etc/selinux/conf and set SELINUX=permissive

use audit2allow, add the following to policy.conf, then run make reload

#line 83
allow httpd_sys_script_t port_type:{ tcp_socket udp_socket } { send_msg recv_msg };
allow httpd_sys_script_t sysctl_kernel_t:dir search;
allow httpd_sys_script_t sysctl_t:dir search;
allow httpd_sys_script_t tmp_t:sock_file write;
allow httpd_sys_script_t httpd_sys_content_t:lnk_file read;
allow httpd_sys_script_t sysctl_kernel_t:file read;
allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto;
lineitems not printing

Templates designed on a UNIX platform don't work on a DOS platform. To make them work load the template either with the builtin template editor or a text editor and save. Templates designed on a Windows platform have the same problem and won't work on a UNIX platform. Once you strip the ^M's the'll work just fine.

Note too that most Linux and UNIX installations come with two utilities for making these conversions: unix2dos and dos2unix. Windows users can obtain these utilities as part of Cygwin.
characterset problems
If you have problems displaying the correct characterset try adding
```
AddDefaultCharset On
```
in your httpd.conf file.
cannot create function
1. Run: createlang -U postgres plpgsql ledgersmb to install the plpgsql language handler into the "ledgersmb" database. More information on this utility can be found at the interactive documentation at the PostgreSQL site.
IDENT Authentication failed for user "ledger-smb"
Edit pg_hba.conf and change authentication to
```
  local           all        all                         md5
  host            all        all       127.0.0.1/32      md5
```
The file is often in the 'data' directory of your postgresql installation. In some distributions it may be in /etc/pgsql or a similar directory. A file search can be helpful when all else fails.
```
  # find / -name 'pg_hba.conf'
```
WARNING! DO NOT just put a 'host all all trust' in pg_hba.conf unless you know what you are doing; that can introduce a pretty huge security hole.
LaTeX templates

If you don't want to edit tex code by hand, you could use Lyx, Abiword, or any WYSIWYG editor capable of exporting latex code.

LaTeX is somewhat complex to learn, initially, but offers a much superior environment to produce professional-looking forms in postscript and PDF format.
Use without Frames
To use without frames, add ?path=/bin/lynx to the login URL:
```
http://localhost/ledger-smb/login.pl?path=/bin/lynx
```
PDF option disappeared

Edit ledgersmb.conf and set: latex = 1
printing to a printer
Printers are defined in ledgersmb.conf
```
[printers] 
Default = lpr
Color = lpr -PEpson
```
Check in your /etc/printcap file for the names of available printers. If you have LaTeX installed set
```
  latex = 1
```
in ledger-smb.conf
Note: html data entry format is for screen preview. Use the "Print" option from your browser to print to a printer.
beginning balances

Add a GL Journal entry and enter the beginning balance for your accounts. Beginning balances are the balances from your last balance sheet. If you also add open invoices to account for COGS for inventory, add the invoices and make the appropriate adjustments.
establish a beginning inventory

add the parts with a vendor invoice. Use the real cost for the items, not zero. If you use zero cost then the cost of goods will be zero when you sell the item.
Assemblies

Assemblies are manufactured goods assembled from parts, services and assemblies. Because you do not buy assemblies you 'stock assemblies' by adding assembled units to your inventory. The quantity for individual parts is reduced and the quantity for the assembly increased. To disassemble an assembly you simply return the parts to inventory by entering a negative quantity for the number of assemblies to stock.
DBD-Pg not installed

Most modern distributions now package DBD-Pg. If it is not packaged follow this recipe to get it working.
- check if you have the header files for PostgreSQL
  $ find / -name 'libpq-fe.h'
  if nothing shows up install the development package for PostgreSQL
- download and untar DBD-Pg
- set the environment variables POSTGRES_LIB and POSTGRES_INCLUDE
- cd to DBD-Pg directory
  as ordinary user
  $ perl Makefile.PL
  $ make
  $ make test
  if all went well su to root
  # make install
- remove the DBD-Pg directory
script not executing, shows in browser instead
Add
```
  AddHandler cgi-script .pl
```
in your httpd.conf file.
switch display to a foreign language

Load your preferences and select the language.
Language selection is in accordance to ISO 3166-1 standards.
Text shows in English when I use a foreign language

This is because the corresponding entry in the .po file. Add the missing text the appropriate .po
switch to a foreign language for the login and admin screen
Edit ledger-smb.conf and enter the code for the $language variable
```
  language = "de"
```
This is a global change and applies to all logins, individual settings may be changed by setting the language in your Preferences.

LedgerSMB security

  Typical setups:
  
  /usr/local/vh/www                   <- DocumentRoot for virtual host
  /usr/local/vh/ledger-smb            <- Alias for ledger-smb
  /usr/local/vh/users                 <- users directory out of reach

  /usr/local/vh/www                   <- DocumentRoot for virtual host
  /usr/local/vh/www/ledger-smb        <- Alias for ledger-smb
  /usr/local/vh/www/ledger-smb/users  <- users configuration files and tmp space

  <Directory /usr/local/vh/www/ledger-smb/users>  <- disable webserver access
    Order Deny,Allow                                 for users directory
    Deny from All
  </Directory>

The location for the users directory can be specified in ledger-smb.conf

Set permission for the users and templates directory to 711
If you do not want anyone to change the templates with the built-in editor set the files in templates/directory/ to read only or disable the menu item to edit the templates.
You can set up a read-only environment if you disable the menu items to add data. i.e 'Add Transaction' if unchecked you will not be able to add a transaction or repost a transaction. You may look at it but nothing else.
There are various settings for audit control and you may disable reposting entirely or up to a certain date. And with the audit trail enabled you can keep tab of who is doing what.
For PostgreSQL you may also set who has access to the server in the file pg_hba.conf
in addition you can secure the tables from unauthorized access by setting up a different database user and GRANT rights. For instance, users without DELETE rights will still be able to use the program, change customers and vendors, add transactions but will not be able to delete or repost transactions.
To lock all the tables to create a RO system GRANT SELECT rights only.
Other security options include a secure shell, your webserver's authentication system, SSL, encrypted tunnels, ...

Last Updated May 28, 2009

LedgerSMB Sites:

LedgerSMB Wiki

Main LedgerSMB Site

Combined Installation Instructions:

DESCRIPTION:

COPYRIGHT:

LATEST VERSION:

PLATFORMS:

REQUIREMENTS:

FOREIGN LANGUAGE SUPPORT:

INSTALLATION INSTRUCTIONS:

DISTRO AND OS-SPECIFIC NOTES

LedgerSMB for Debian

Installing LedgerSMB 1.2

MANUAL INSTALL

Create Datasets and Users

Load the Accounting Program

FTP INSTALLATION

OTHER ISSUES:

SET UP A USER:

LOAD THE ACCOUNTING PROGRAM:

INSTALLATION CHECKLIST:

In the Database section enter

IF SOMETHING DOESN'T WORK:

TROUBLESHOOTING

Error: Access Denied in admin.pl

Error: "No GlobalDBH Configured or Could not Connect"

FAQ (Frequently Asked Questions)

Printing to a Printer from a Windows Server

Error on converting from SQL-Ledger: ERROR: column "chart_id" contains null values

SELinux

lineitems not printing

characterset problems

cannot create function

IDENT Authentication failed for user "ledger-smb"

LaTeX templates

Use without Frames

PDF option disappeared

printing to a printer

beginning balances

establish a beginning inventory

Assemblies

DBD-Pg not installed

script not executing, shows in browser instead

switch display to a foreign language

Text shows in English when I use a foreign language

switch to a foreign language for the login and admin screen

LedgerSMB security