transactor.conf

NAME
SYNOPSIS
DESCRIPTION
SYNTAX
STRUCTURE AND COMMANDS
NOTES
EXAMPLES
FILES
SEE ALSO
COPYRIGHT
AUTHOR

NAME

transactor.conf - Configuration file for Transactor

SYNOPSIS

transactor -c configfile [OPTION]...

DESCRIPTION

This manual page describes the configuration file of transactor, an general purpose transaction coordinator.

SYNTAX

The configuration file is a sequence of tokens, separated by whitespace. Line breaks are not significant, they count as whitespace.
A hash sign starts a comment that extends to the end of line.
There are the following kinds of tokens:
Literal Text
Text and symbols printed in this style must be used as-is.
STRING
A string is a either a C-style quoted string, or a bareword.
A C-style quoted string is a sequence of characters, enclosed in double quotes, that follows the same rules as a string literal in the C programming language; that is, certain characters like ", ', \, and all non-graphic ASCII characters must be escaped with a backslash as in C.
A bareword is a sequence of non-whitespace ASCII characters that does not start with double quotes. Hash signs in the middle of the word are allowed and are treated as part of the bareword. Hash signs at the start of the bareword are not possible; those are treated as comment.
So, if you have a string without blanks like ``abc-123-'', you can specify it as "abc-123-\" or as abc-123-\. A string with blanks must be specified in C-style.
NUMBER
A number is a sequence of decimal digits.

STRUCTURE AND COMMANDS

CONFIGFILE:
SYSLOGCONF
DAEMONCONF
SERVICECONF
ADMINCONF
TLOGCONF
MLOGCONF
NETCONF
PEERLIST
The configuration file has the following parts, all of which must be present in the sequence given:
Syslog behaviour configuration, daemon configuration, configuration of the service port and the admin port, configuration of the local transaction log and message log, configuration of the local transactor peer-to-peer networking, and a list of all peer transactors with their networking configuration.
SYSLOGCONF:
logname STRING
logfacility
STRING
Those commands define the application name that is given in syslog messages, and the log facility to be used. The log facility must be one of the following strings: "auth", "authpriv", "cron", "daemon", "ftp", "kern", "local0", "local1", "local2", "local3", "local4", "local5", "local6", "local7", "lpr", "mail", "news", "syslog", "user", "uucp", or the empty string. The respective argument will be passed to openlog().
DAEMONCONF:
username STRING
groupname
STRING
pidfile
STRING
signal_dumpfile
STRING
If the username string and/or the groupname string is not empty, transactor will attempt to switch the user id and/or group id to the specified values. The id's can be given as name or number.
Note that switching user will be done before network ports are opened, so the network ports must probably be above 1024 in this case.
If the pidfile string is not empty, transactor will attempt to write its process id to the specified file in text form, followed by a single newline character. The pid file can be used by start/stop scripts to identify transactor's process.
The pidfile must be specified with an absolute path.
If transactor finds such a file on startup, and the process in the file is that of a running process, it will refuse to start.
If the signal_dumpfile string is not empty, transactor will write a dump of its internal state to the specified file whenever it receives a SIGUSR1, SIGUSR2, or SIGHUP signal.
SERVICECONF:
server_port STRING
server_max_clients
NUMBER
client_timeout
NUMBER
client_keepalive_interval_ms
NUMBER
client_keepalive_timeout_ms
NUMBER
The server_port string specifies the port on which transactor is offering its services. To this port the application servers should connect. The string consists of an optional hostname or IP address, a colon, and a mandatory port number or name.
The server_max_clients number gives the maximum number of application servers that can connect to the service port concurrently. Note that transactor is not designed to serialize multiple local clients efficiently; there are better methods available for that purpose on each operating system. It is strongly recommended that only one client connects to transactor at a time, or that multiple connected clients serialize their post requests to the transactor by external means.
The client_timeout parameter specifies a timeout in ms for the service port; the timeout applies whenever transactor needs to receive or send data and there is no progress. When the timeout expires, the application server will be disconnected. The timeout does not apply to an idle time when the client (application server) just issues no commands. A timeout value of 0 means no timeout.
If the client_keepalive_interval_ms parameter is set to a nonzero value, transactor will send very primitive keepalive pings (consisting in the five bytes pingn) in regular intervals to the client (the application server), to which the client must answer by a pongn message unless it has other data to send (in which case the pong need not be sent). The pong answer must be received within client_keepalive_timeout_ms milliseconds.
For information on the commands that are available to the client, see the section CLIENT COMMUNICATION PROTOCOL in the manpage of transactor(8).
ADMINCONF:
admin_port STRING
The admin port is for administrator access to transactor during operation, to analyze or debug its behaviour. For more information, open a telnet connection to this port and say helpn.
On this port, the same commands as for the regular service port are available.
TLOGCONF:
tlog_base_directory STRING
The tlog_base_directory string specifies the path name of the base directory of the transaction log. See the manpage of transactor_tlog(5) for a description of the format.
The transaction log base directory must exist when transactor is started, and must be readable, writeable, and searchable by transactor.
MLOGCONF:
mlog_file STRING
The mlog_file string specifies the path name of the message log file. See the manpage of transactor_mlog(5) for a description of the format.
The message log file must exist when transactor is started, and the directory containing the file must be readable, writeable, and searchable by transactor, as well as the message log file itself.
NETCONF:
local_node_name STRING
[ tcp STRING ]
[ udp STRING ]
The network configuration of the local node must specify the local node name, optionally followed by a default local TCP and a default local UDP port.
The local node name should be a short string that is unique within the cluster of transactors. The same string must be used in the configuration files of the peer transactors, where the local transactor appears in the peer list.
The optional local default TCP port specification gives a string that specifies a local TCP port to be used to communicate with peers; that port can be overridden by a peer-specific local TCP port specification in the peer list.
The optional local default UDP port specification gives a string that specifies a local UDP port to be used to communicate with peers; that port can be overridden by a peer-specific local UDP port specification in the peer list.
PEERLIST:
{
[PEERCONF ...]
}
The peer list is enclosed in curly braces; it is a sequence of 0 or more peer configurations.
PEERCONF:
peer STRING
[ local tcp STRING ]
[ local udp STRING ]
tcp
STRING
udp
STRING
udp_maxsize
NUMBER
[ encryption_key STRING ]
A peer configuration starts with the keyword peer, followed by the peer name string. This is the same string as the local node name at the peer transactor.
Optionally the peer name is followed by the specifications of the local TCP port, and the local UDP port, to use. This overrides the default local TCP or UDP port given in the NETCONF specification. If the default local TCP or UDP ports have not been specfied in the NETCONF specification, they must be specified here.
These optional specifications are followed by mandatory TCP and UDP port specifications of the peer transactor.
The udp_maxsize parameter specifies the maximum size of packets (in bytes) to be sent via UDP. For a working UDP connection, this size should be specified as 10000. If UDP path MTU discovery does not work properly on the network between the local transactor and the peer, the udp_maxsize parameter can be used to restrict the size of UDP packets to be sent, or even (by setting it to 0) prohibit UDP altogether.
An optional encryption_key parameter can be specified, which causes transactor to encrypt all communication with its peers. This key should have at least 50-60 characters. From the key, a 26 bit field for AES encryption will be generated. Transactor uses AES encryption in ECB mode; see the SECURITY section in the manpage of transactor(8).

NOTES

The peer list in the configuration file need not be sorted. The peers will be sorted internally by peer name with strcmp(). If a node sorts before another, the previous node in the sorting order will actively start the TCP connection, while the latter node will listen passively. The active node will ignore the port number of its local tcp port specification, and use an ephemeral port for connecting.
If multiple peers use the same IP address (for instance when multiple instances of transactor are used on the same computer to simulate a distributed cluster), connection establishment between the peers could not work correctly. See the explanation in the NETWORKING section of the manpage transactor(8).

EXAMPLES

Minimum Configuration File
A minimum transactor configuration can be set up with the following commands. This creates a cluster with a single transactor instance that offers its service on port 2000:
mkdir -p /var/transactor
mkdir -p /var/transactor/tlog
:>/var/transactor/mlog
cat >/etc/transactor.conf <<EOF
logname "transactor"
logfacility ""
username ""
groupname ""
pidfile ""
signal_dumpfile "/tmp/transactor_dump"
server_port "127.0.0.1:2000"
server_max_clients 10
client_timeout_ms 0
client_keepalive_interval_ms 0
client_keepalive_timeout_ms 0
admin_port  "127.0.0.1:2001"
tlog_base_directory "/var/transactor/tlog"
mlog_file "/var/transactor/mlog"
local_node_name "A"
{
}
EOF
transactor -c /etc/transactor.conf


You can now test this configuration like that:


telnet localhost 2001
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
subscribe 1
status 1 0 majalive uptodate 0 1 not_started
post 17 1 "testdata"
post_response 17 posted 0:1 1
tlog_tspec tid 1 sid 0:1 size 8
testdata
quit
bye
Connection closed by foreign host.
Sample Configuration File
#
# Sample Transactor Configuration File
#
# Copyright 2003 Claus Fischer
#

###
#   Syslog configuration
###
logname "transactor"
logfacility "local2"


###
#   Daemon configuration
###

# If transactor should switch to a particular uid/gid,
# put the uid or username in the string.
# Note that this happens before transactor opens its
# networking ports, so those ports should probably
# be above 1024.
username ""
groupname ""

# If transactor should write a pid-file, put the
# filename in the string.
#
# If transactor finds such a file on startup, and the
# process id in the file is that of a running process,
# it will refuse to start.
#
# Please use an absolute path.
pidfile ""


###
#   Transactor service
###

# If the transactor receives a SIGUSR1,SIGUSR2 or
# SIGHUP, it will dump the internal state to this
# file.
# If the filename is empty, it will not dump.
signal_dumpfile ""

# Transactor offers its service on a local port
# to other programs as clients.
#
# Note:
#
# Transactor is designed to handle serialization
# of transactions among multiple transactors
# participating in a distributed system.
#
# Transactor is NOT designed to serialize requests
# for multiple local clients efficiently. There
# are better methods available for that purpose
# on each operating system.
# If two or more local clients propose transactions
# simultaneously, transactor will work correctly
# and pick one specification, ultimately, as the
# winner, but a lot of obsolete transaction data
# might be sent across the network, wasting bandwidth.
#
# Therefore, it is strongly recommended that only
# one client be connected on each node where
# transactor runs. The client should handle
# serialization of incoming requests for transactions.
# If you use multiple clients, they should probably
# coordinate among themselves and pick one to propose
# the next transaction.
#
server_port "127.0.0.1:3101"
server_max_clients 10

# Client timeouts
#
# Those parameters define how the client is handled.
# The timeout applies only when data is due to be
# sent/received. The keepalive sends a "ping0 message
# that must be answered by a "pong0.
client_timeout_ms 10000
client_keepalive_interval_ms 300000
client_keepalive_timeout_ms 10000

# Admin port
#
# This port is for administrator access to the
# transactor during operation, to analyze or
# debug its behaviour.
# You can telnet to it, and say 'help' for more
# information. Many commands are the same as for
# the regular server port.
admin_port "127.0.0.1:3201"

# Transaction log
#
# The transaction log is an eternal log of all transaction
# data coordinated through transactor. It is organized in
# subdirectories under the tlog_base_directory, with 100
# files/directories at most in one directory.
# You may remove old transactions at your own risk; as long
# as all transactors on all nodes are beyond that transaction
# and no client will ever request the data, that is fine.
# You must not remove partial files.
# Note that before removing old files, you should change the
# search algorithm in tlog.c that identifies the last
# transaction in the tlog.
tlog_base_directory "/var/transactor/tlog"

# Message log
#
# The message log is a rotating log of currently relevant
# messages. It is purged on transactor startup, and then
# at times when it seems opportune. It may grow to very
# large sizes if large transactions are handled by the system.
# The directory holding it must allow for creation of new
# files, renaming and deleting of files, as the message
# log must be atomically replaced.
mlog_file "/var/transactor/mlog.dat"

###
#   Peer networking
###

# Peer-to-peer networking of transactors
#
# All transactor nodes use a short node name which must
# be known to all other nodes in the system. A transactor
# will typically use one UDP and one TCP port on the local
# system, and additional ephemeral TCP ports for outgoing
# connections as required.
# It is possible, though, to use a different local UDP or
# TCP port for each peer, since each transactor is connected
# with each other point-to-point. This is shown in the sample
# for peer d.
# The peers will be internally sorted by name (with strcmp()),
# then numbered from 0 upwards. For UDP, the connection is
# fully symmetric. For TCP, the peer with the lower index
# will connect, and the peer with the higher index will listen.
# Both TCP and UDP communication uses messages of up to roughly
# 5000 bytes. On networks that have a reasonably reliable UDP
# connectivity, this should be the preferrable transport.
# Transactor will handle the removal of duplicates, timeouts
# and retransmissions just fine, and UDP is more lightweight
# than TCP.
# Networks with limited packet size are expected to perform
# proper path MTU discovery on the UDP ports (the sockets are
# bound and connected so that both addresses are known to the
# OS). However, there may be many situations in the real world
# where UDP messaging does not work well with larger packets,
# or UDP should not be used at all. For this purposes, a
# maximum UDP message size can be specified; if it is set to 0,
# all messages will be sent over TCP.
# To encrypt the packets sent and received, specify an
# encryption_key. This key should have at least 50-60 characters.
# From this key, a 256 bit field for AES encryption will be
# generated.

local_node_name a
tcp "127.0.0.1:3001"
udp "127.0.0.1:3001"
{
    peer b
        tcp "127.0.0.2:3002"
        udp "127.0.0.2:3002"
        udp_maxsize 10000
    peer c
        tcp "127.0.0.3:3003"
        udp "127.0.0.3:3003"
        udp_maxsize 10000
     # Use encrypted connection to c
     encryption_key
           "blablaepfoah;gaghaighawiughagiahgaighaewrighargiawge"
    peer d
        # Local ports to use specifically for this connection
        local tcp "127.0.0.1:3001"
        local udp "127.0.0.1:3001"
        tcp "127.0.0.4:3004"
        udp "127.0.0.4:3004"
        udp_maxsize 10000
    peer e
        tcp "127.0.0.5:3005"
        udp "127.0.0.5:3005"
        # UDP to this peer is unreliable
        udp_maxsize 0
}

# Since the above configuration uses five nodes, a minimum of
# three must be alive to get the system going.

# How to change peers:
#
# Note that once the peer list is defined, it should not be
# changed. The problem is in the message log, which contains
# messages from all peers and relies on proper peer indexing.
#
# If the peer configuration should be changed, all clients
# should be disconnected from the transactors, then the
# transactors should be given enough time (and a working network)
# to finish the last transaction before being shut down.
# Finally, the message logs of all nodes should be emptied.
#
# After startup, the transactors will restart numbering
# specifications with sid's of 1 upwards. That should not be
# a problem, as the value of the sid is irrelevant once the
# transaction is completed.

FILES

/etc/transactor.conf
The location of the configuration file is not hardcoded in the program but must be specified on the commandline.

SEE ALSO

transactor(8), transactor_mlog(5), transactor_tlog(5)

COPYRIGHT

Transactor is Copyright 2003, 2004 Claus Fischer

AUTHOR

Transactor was written by Claus Fischer <transactor@clausfischer.com>.