Once you have installed (see Chapter 2, Installation) and configured (see Chapter 3, Configuration) your environment, you are ready to run LIXA.
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.
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
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
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).
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.
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)
Some additional options are available: they don't radically change the state server behavior, but supply some features.
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
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.
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.
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.