Cardbox Server under Linux

The Cardbox Server is available for Intel x86 builds of Linux.

Downloading

Download the Linux Cardbox Server here.

Installation

What you have downloaded is a compressed archive called cshared.tar.gz that contains the Cardbox server program. Before you can run the program, you need to uncompress it and extract it from its archive.

Choose the name of the directory where you want to install the Cardbox server.
If the directory does not already exist, use mkdir to create it.
Use cd to make this into your current directory.
Enter the command
tar -xzvf cshared.tar.gz
- If the downloaded file was in a different directory, specify its full pathname in the tar command.
tar will report the program name as it decompresses it: this will be cardbox-shared.

Configuration

Until you have configured the server, running it will do virtually nothing. Clients will be able to connect to it, but they will not be able to access any files at all.

Location of configuration file

The operation of the Cardbox Server is controlled by one configuration file, called server.ini. By default this is stored in the current directory at the time that the Cardbox Server is started, but you can use a different location. You can specify the different location during server startup, or you can create a simple two-line dummy file called server.ini in the current directory:

[Files] server.ini=filename

where filename is the full path name of the configuration file you want to use.

The contents of server.ini for Linux are identical to those for Windows, so one option is to set up the Cardbox Server on a Windows machine, use the Cardbox Server control in Windows to set all the options, and then copy server.ini across to your Linux machine. If you don't want to do this, then the details of server.ini are listed below.

Format of configuration file

server.ini has the same format as standard Windows initialisation files: You must not have two sections of the same name, or two items of the same name in the same section. In item and section names, case is ignored, so that [Files], [FILES], and [files] are all the same.

[First section name] item1=value ; comment item2=value [Second section name] item=value

etc

In the descriptions given below, we will show the section name above each item. When you are putting together a server.ini file, remember to use each section name once only, and to put all the items for that section below that single occurrence of the section name.

Page references are to pages in the Cardbox Server Book.

Server page (p.21)

Server identification

[Server] Description=Harriet's trial installation

If you do not specify this then no server identification will be reported to Cardbox users.

Access to databases

[Server] Access=RW

If you do not specify this then access will be read-only.

Connections page (p.22)

Accept client connections

[Server] IP Address=80.89.222.10

If you do not specify this then the default is 0.0.0.0, meaning "Listen on all connections".

Also accept loopback connections

[Server] Loopback=1

If you do not specify this then the default is 0, meaning "do not accept loopback connections in addition to connections on the designated IP address".

Port number

[Server] Port=1234

If you do not specify this then port 3105 will be used.

Licences page (p.24) - no longer needed for Cardbox 3.1

User licences `[Licences] 12345678=`	For each user licence, put a line in the [Licences] section that contains the licence number followed by an equals sign.
`[12345678] Type=P Users=3 Signature= 5759-XX50-0666-29X7`	For each user licence, create a section with the licence number as the section name followed by the licence details as shown. Type is P for Professional Edition licences, U for read/write user licences, and R for read-only user licences.
Lend Cardbox Professional licences `[Licence Lending] Enable=1`	If you do not specify this then licence lending will not be enabled..
Valid codes `[Licence Lending] Codes=Cat Dog Mouse`	If you do not specify this then the Cardbox Server will not demand a loan code before lending a licence.

Files page (p.31)

Two sections in the initialisation file tell the Cardbox Server what databases are accessible to users:

[Named Files] lists databases whose names are visible in the File > Open > Server command.
[Hidden Files] lists databases which are not listed but which can be opened if the user knows the name and types it in.

The format of each section is the same:

databasename = filenameNote that filename is the name of the database file as viewed from the Cardbox Server's computer, not a user's computer. Also, Linux filenames are case-sensitive. Cardbox expects lower-case file extensions such as .fil and .fmt.

For example:

[Named Files] Active Invoices = /home/serveruser/samples/actinv.fil

Databasename (Active Invoices) is the name of the database as it will be seen by the user. It can be in upper and lower case and it can contain spaces. Filename (/home/serveruser/samples/actinv.fil) is the name of the database's .fil file on the computer where the Cardbox Server is running. There is no need for this file to be accessible to users in any other way (such as network file sharing), and for optimum security it is better if it isn't accessible.

You can disable a filename entry by preceding it with a colon:

:Active Invoices = /home/serveruser/samples/actinv.fil

Automatic directory (p.35)

Automatic directory

[Automatic Directory] Path=/home/cardbox/userdir

If you do not specify this then no automatic directory will be provided.

Allow users to create databases

[Automatic Directory] Creation=1

If you do not specify this then users will not be allowed to create databases in the automatic directory.

Password for database creation

[Automatic Directory]

        Creation Password=Secret007

If you do not specify this then users will not be asked for a password before creating databases in the automatic directory. When it sees this entry, the Cardbox Server will replace it with an entry called Hashed Creation Password, in which the password has been replaced with a "hash code", so that if someone reads the server.ini file he will not know what password to use.

Admin page (p.39)

Server Administration password

[Server] Administration Password=Special2000

If you do not specify this then no remote server administration will be allowed. When it sees this entry, the Cardbox Server will replace it with an entry called Hashed Administration Password, in which the password has been replaced with a "hash code", so that if someone reads the server.ini file he will not know what password to use.

Launch file backup

[Backup] Owner=123.45.67.89

You cannot specify a list of IP addresses but you are allowed wildcards (eg. 192.103.*.*).

The default setting is 127.0.0.1, which means that the browser that starts a backup must be on the same computer that is running the server. If you want to disable IP address authorisation altogether, so that everyone needs to have a user name and password even if they are running their browser on the same computer as the server, use the entry

[Backup] Owner=

User name and password

[Backup]

        Password=cat:mouse

If you specify this then your browser will ask for a user name and password when you try to access the backup page: in this case, the user name is cat and the password is mouse. When it sees this entry, the Cardbox Server will replace it with an entry called Hashed Password, in which the password has been replaced with a "hash code", so that if someone reads the server.ini file he will not know what password to use.

IP address authorisation and password authorisation are inclusive: if you specify them both, then anyone who either has a suitable IP address or has the right user name and password will be allowed to perform backups.

Security page (p.42)

Server's built-in access code `[Server] Access Code Mode=1`	This is the default setting if you do not specify Access Code Mode.
No access code `[Server] Access Code Mode=0`
Specified access code `[Server] Access Code Mode=2 Access Code=12345`	When it sees this entry, the Cardbox Server will replace Access Code with an entry called Hashed Access Code, in which the access code has been replaced with a "hash code", so that if someone reads the server.ini file he will not know what access code to use.
Do not allow database encryption `[Server] Allow Database Encryption=0`	If you do not specify this then the Cardbox Server will allow users to encrypt unencrypted databases (subject to appropriate authorisation through access codes or master passwords).
Allow access by other programs `[Server] Allow Middleware=1`	If you do not specify this then programs other than Cardbox will not be allowed to use this Cardbox Server.

Log page (p.44)

Write log information to `[Files] server.log=/var/log/cboxserver.log`	If you do not specify this then the server.log file is placed in the same directory as server.ini.
Log file size limit `[Server] Log limit=2MB`	If you do not specify this then the limit is 10 megabytes.
Log rotation `[Server] Log backups=2`	When the log file is full, Cardbox gives the full log file a new name and creates a new log file so that it can continue logging. By default, `server.log` is renamed to `server.1`, any existing `server.1` file is renamed to `server.2`, and any existing `server.2` file is deleted. You can change the number of files to be retained under Linux by changing this entry. If you do not specify it then the default value is 2, which gives the behaviour we have just described.
Event categories to log `[Debug] LogMask0=4294967294 LogMask1=4294967295`	If you do not specify this then the value 0 is assumed, meaning that none of the optional event categories are selected. To construct LogMask0, start with the value 0. Add 2 if event 1 is selected, 4 if event 2 is selected, 8 if event 3 is selected, and so on, doubling each time, up to 2147483648 if event 31 is selected. To construct LogMask1, start with the value 0. Add 1 if event 32 is selected, 2 if event 33 is selected, and so on up to 2147483648 if event 63 is selected.

Starting and stopping the server

Console operation

You would not normally run the Cardbox Server from the console but it can be good to do so when testing an initial configuration. When you run the Cardbox Server from the console, all log output is done to the console as well as to the log file.

To start the server manually, simply run it from the command line:

./cardbox-shared

To terminate a manually started server, press Ctrl+C.

Background operation

To launch the Cardbox Server as a "daemon", so that it runs continuously in the background even after you have closed your current console session, use the following command line:

./cardbox-shared -d

Terminating a background Cardbox server

To terminate a background Cardbox Server, first get its process ID by whatever means you find most appropriate: for example,

ps -A | grep cardbox

Supposing that the PID reported by this command is 24680, you should then use the kill command as follows:

kill 24680

It may take a few seconds for the Cardbox Server to stop, because it has to write any unwritten data to the disk.

Changing the location of server.ini

If you want server.ini to be somewhere other than the current directory at the time that the Cardbox Server starts, or if you can't be sure of what the current directory will be at startup, set an environment variable called server.ini and make its value the full pathname of your intended server.ini file.

Changing configuration while the server is running

If you have the Cardbox Server running in the background, you can change various configuration parameters without having to stop it and restart it.

To do this, edit server.ini, save the changes, and then send the Hangup (SIGHUP) signal to the Cardbox Server process. First get its process ID by whatever means you find most appropriate: for example,

ps -A | grep cardbox

Supposing that the PID reported by this command is 24680, you should then use the kill command as follows:

kill -HUP 24680

The Cardbox Server will then re-read server.ini. This does not cause any interruption to the service to users.

Automated startup

We don't provide rc.d scripts for starting and stopping Cardbox because different Linux distributions differ in the structure that they use for rc.d files, but you should find it relatively straightforward to construct your own scripts based on the manual instructions we have given you.

Error messages during startup

The commonest error message when starting the server is

Could not bind socket: retcode=10048 (EADDRINUSE)

EADDRINUSE is an error defined by Sockets - the software layer that interfaces between programs (such as Cardbox and Web browsers) and the Internet protocol.

The official definition of the error is "Address already in use" - which means that some other program is using the same IP address (essentially, the address of your machine) and the same port number (which distinguishes one program from another: we have used port 3105 for the Cardbox server.

The likeliest causes for this error message are:

You are trying to start the Cardbox Server when there is already a Cardbox Server running and listening to the same port.
You have just shut down the Cardbox Server but some TCP connections from the server session have not completely shut down. You can use netstat or a similar program to check this: you may have to wait a minute for Linux's timeouts to finish closing the connections.
You have a firewall program which is "protecting" you from using port 3105, by pretending to other programs that the port is already in use. You will have to re-configure the firewall to allow you access to this port: how you do this varies from one firewall to another.

Viewing server status

To view the status of a Cardbox server, connect to port 3105 using a Web browser. For example, if the Cardbox server is running on a machine called database.mysystem.com, tell your Web browser to retrieve the Web page

http://database.mysystem.com:3105/status.htm

To view the status and have it refreshed every 30 seconds, use the following variant:

http://database.mysystem.com:3105/status.htm?Interval=30

The status display tells you how long the server has been running and the quantity of data it has transferred; and for each client, it lists the files that the client is currently using.

Cardbox