Chapter 4. Execution

Once you have installed (see Chapter 2, Installation) and configured (see Chapter 3, Configuration) your environment, you are ready to run LIXA.

Note

In this chapter it is assumed you installed the LIXA project software at the default path /opt/lixa; if you installed the software at a different path, you'd need to adjust the shown commands consequently.

Starting the state server (lixad)

The first step you must perform is starting the state server; it's name is lixad (LIXA daemon). The command

tiian@ubuntu:~$ /opt/lixa/sbin/lixad --help
Usage:
  lixad [OPTION...] - LIXA server

Help Options:
  -?, --help             Show help options

Application Options:
  -d, --daemon           Run the process as a daemon
  -m, --maintenance      Start the server in maintenance mode only
  -u, --dump             Dump the content of status files using order [ufs] (u=used, f=free, s=sequential)
  -c, --config-file      Specify an alternate configuration file
  -t, --trace-file       Specify trace file name
  -l, --clean-failed     Clean recovery failed transactions at start-up
  -v, --version          Print package info and exit
    

displays the available command line options.

If you tried to start the state server without the appropriate privileges it should happen something like this:

tiian@ubuntu:~$ /opt/lixa/sbin/lixad
tiian@ubuntu:~$ sudo su -c "tail /var/log/daemon.log"
[...]
Mar 31 22:53:10 ubuntu lixad[5891]: LXD000N this process is starting a new LIXA server (lixa package version is 0.5.29)
Mar 31 22:53:10 ubuntu lixad[5891]: LXD015W unable to open pid file '/opt/lixa/var/run.pid'
Mar 31 22:53:10 ubuntu lixad[5891]: LXD004E error (ERROR: 'open' function returned an error condition) while starting manager(s), premature exit
      

because the process is not able to update the content of the /opt/lixa/var/ directory; use the administrative user and try again:

tiian@ubuntu:~$ sudo su - lixa
[sudo] password for tiian:
lixa@ubuntu:~$ /opt/lixa/sbin/lixad
      

Running the command without options blocks your shell and runs the state server in foreground; this is not terribly useful but it may help you when you are debugging some issue. Use these commands, from a different terminal, to retrieve the PID (process id) and to stop the state server:

tiian@ubuntu:~$ sudo su - lixa
lixa@ubuntu:~$ ps -ef|grep lixad|grep -v grep
lixa      5909  5906  0 22:56 pts/1    00:00:00 /opt/lixa/sbin/lixad
lixa@ubuntu:~$ kill 5909
lixa@ubuntu:~$ exit
logout
    

Alternatively you can strike ^C to break the foreground execution. A foreground execution is generally more useful if some tracing is enabled:

lixa@ubuntu:~$ export LIXA_TRACE_MASK=0x00000001
lixa@ubuntu:~$ /opt/lixa/sbin/lixad 
2011-03-31 22:58:32.244333 [5920/3073509104] lixad/main: starting
2011-03-31 22:58:34.864062 [5920/3073509104] lixad/main: exiting
    

Background (daemon) execution

The most useful command option is --daemon: it allows you to run the state server as a daemon detached from any terminal:

lixa@ubuntu:~$ /opt/lixa/sbin/lixad --daemon
lixa@ubuntu:~$ ps -ef|grep lixad|grep -v grep
lixa      5926     1  0 22:59 ?        00:00:00 /opt/lixa/sbin/lixad --daemon
      

when running the state server as a daemon you need to perform some special tasks to understand the process is up & running. With ps -ef|grep lixad|grep -v grep you can verify the process is running. The state server registers its PID in a special file: /opt/lixa/var/run.pid; if the content of the file is different than the result retrieved with the grep command, something is not running well.

lixa@ubuntu:~$ cat /opt/lixa/var/run.pid 
5926
      

To stop a daemonized state server you must use the kill command as shown below:

lixa@ubuntu:~$ kill $(cat /opt/lixa/var/run.pid)
lixa@ubuntu:~$ ps -ef|grep lixad|grep -v grep
      

The grep command returns an empty result because the state server is not running. The state server publishes some messages using the syslog facility; Ubuntu 8.04 sends default messages to the file /var/log/daemon.log; below there are some standard messages:

tiian@ubuntu:~$ sudo su -c "cat /var/log/daemon.log|grep lixad|grep 5926"
Mar 31 22:59:11 ubuntu lixad[5926]: LXD014N LIXA server entered daemon status
Mar 31 23:00:48 ubuntu lixad[5926]: LXD019N received signal 15, server immediate shutdown in progress...
Mar 31 23:00:48 ubuntu lixad[5926]: LXD006N server terminated activities
      

Maintenance mode execution

The --maintenance option allows you to start the state server to perform some special actions; only special clients can connect to the server when the server is operating in maintenance mode: customer developed Application Programs can not perform distributed transactions. A special client is lixar: a command line utility designed for recovery purposes (see Chapter 9, Recovery for more information).

Warning

A state server that's operating in maintenance mode is not serving the LIXA infrastructure and Distributed Transaction Processing can not be performed: use this option only if you really need it.

There's no way to turn a server operating in maintenance mode in a server operating in standard mode: you have to stop and start the LIXA state server again.

Dump execution

Use --dump option to get a dump of the content of the state currently persisted in the status files. The option must specify one or more flags:

  • "s": dump all the blocks, in sequential order

  • "u": dump all the used blocks, travelling the used block chain

  • "f": dump all the free blocks, travelling the free block chain

You may specify two or more flags on the same command line: the output will duplicate some blocks.

The example below shows the output produced when dumping the content of a single status file with no current transactions in progress (the free block chain contains all the blocks):

tiian@ubuntu:~$ sudo su - lixa
lixa@ubuntu:~$ /opt/lixa/sbin/lixad --dump f
========================================================================
First file ('/opt/lixa/var/lixad_status1_1') will be dumped
Magic number is: 24848 (24848)
Level is: 1 (1)
Last sync timestamp: 2011-03-31T23:00:48.829787+0200
Size: 10 blocks
Used block chain starts at: 0 (empty chain)
Free block chain starts at: 1
Dumping records following physical order: 0
Dumping records following free block chain: 1
Dumping records following used block chain: 0
------------------------------------------------------------------------
Block: 1, next block in chain: 2
Block type: unknown (0)
------------------------------------------------------------------------
Block: 2, next block in chain: 3
Block type: unknown (0)
------------------------------------------------------------------------
Block: 3, next block in chain: 4
Block type: unknown (0)
------------------------------------------------------------------------
Block: 4, next block in chain: 5
Block type: unknown (0)
------------------------------------------------------------------------
Block: 5, next block in chain: 6
Block type: unknown (0)
------------------------------------------------------------------------
Block: 6, next block in chain: 7
Block type: unknown (0)
------------------------------------------------------------------------
Block: 7, next block in chain: 8
Block type: unknown (0)
------------------------------------------------------------------------
Block: 8, next block in chain: 9
Block type: unknown (0)
------------------------------------------------------------------------
Block: 9, next block in chain: 0
Block type: unknown (0)
      

Note

The dump can be performed while the state server is running: the dump will output the content of the currently sinchronized status file and you will not be able to see the last updates. Dumps performed at different times may produce different results if there is a running state server.

Additional options

Some additional options are available: they don't radically change the state server behavior, but supply some features.

Specifying a different configuration file

With option --config-file you can specify a non default configuration file; this option can be useful if you want to test a different configuration without damaging your production config file. It can be used if you want to run different instances of the state server in the same operating system image, too.

Below there is a sample invocation:

lixa@ubuntu:~$ /opt/lixa/sbin/lixad --config-file /tmp/lixad_conf.xml
	

Specifying a trace file

With option --trace-file you can specify a different trace file instead of the default stderr process stream; this option is especially useful when you are running the state server as a daemon (see the section called “Background (daemon) execution”). Below there is a sample invocation:

lixa@ubuntu:~$ export LIXA_TRACE_MASK=0x01
lixa@ubuntu:~$ /opt/lixa/sbin/lixad --daemon --trace-file /tmp/lixad.trace
lixa@ubuntu:~$ ls -la /tmp/lixad.trace
-rw-r--r-- 1 lixa lixa 349 2011-03-18 16:14 /tmp/lixad.trace
	

Take a look to the section called “Tracing” for additional details.

Clean-up recovery failed transactions

Use option --clean-failed to clean-up the state of the transactions that LIXA was not able to recover automatically: this option is useful to remove useless information from the state file, but you must pay attention to these warnings.

  • If your LIXA installation worked properly, you would not need to clean-up the state file.

  • Removing recovery failed transactions cleans-up the history of your issues: you should understand why your state file is accumulating recovery failed transaction records need to clean-up the state file.

Don't use this option without a deep review of the content of Chapter 9, Recovery.

Retrieving software version

Use option --version to retrieve the version of the installed software as shown below:

lixa@ubuntu:~$ /opt/lixa/sbin/lixad --version
LIXA: a Libre XA implementation
Copyright (c) 2009-2012, Christian Ferrari; all rights reserved.
License: GPL (GNU Public License) version 2
Package name: lixa; package version: 0.5.29
Access http://sourceforge.net/projects/lixa/ to report bugs and partecipate to the project
	

The lixad command does not start a real state server: it prints version information on stdout and exits.