OS4X Core binaries

os4xeq

Add a file to the send queue or enqueue an EERP message to the EERP queue. If the addressed partner is configured for OFTP2, special file handling is available for the following virtual filenames:

• ODETTE_CERTIFICATE_REQUEST: request certificate from remote partner
• ODETTE_CERTIFICATE_DELIVER: send the configured certificate to the partner (also used by updating certificate)
• ODETTE_CERTIFICATE_REPLACE: send the configured certificate to the partner as an instant replacement

When an existing send queue entry already exists (server ID doesn't matter!), then it will be checked if it's blocked. If it's blocked, it will be unblocked, otherwise it will be removed and newly added. If any process is running for that send queue entry (i.e. a process in the status "taken by send queue"), it will recognize that its send queue entry was removed and it will cleanly shut down.

The parameter "-m" accepts a relative filename (without path information) for moving or copying the resulting file (which is then added to the send queue) to the OS4X's temporary directory with the given name.

If the destination partner settings use any kind of OFTP2 action (like signing, encryption or compression) and the format is given as "V" (variable record length mode) via parameter "-G", the file will be transcoded to the given structure before any other action will be made. So, as a result of this automatic transformation, you don't have to pre-transform the file on your own.

input parameters

• -h: printf this help text
• -C <configfile>: use given config file (default: /etc/os4x.conf)
• -p <partner shortname>
• -A <partner longname>
• -b <partner index value>
• -f <filename with absolute path>
• -v <virtual filename>
• -c <comment (max. 255 chars./without special chars.)>
• -q <alternative SSID for this file (originator)>
• -r <alternative SSID for this file (destination)>
• -s <alternative SFID for this file (originator)>
• -t <alternative SFID for this file (destination)>
• -w <alternative password for this file (originator)>
• -x <alternative password for this file (destination)>
• -u <priority, default: 0>; numeric
• -i <server ID, default: 0>; numeric
• -P: add file passive to send queue (let partner fetch it from remote)
• -d: <optional file description in OFTP2 session>
• -m <filename> move temporarily created OFTP2 file to OS4X's temporary directory with the given name
• -V: print out version and exit
• -F <n>: send file in fixed record length mode with n bytes maximum record length; overrides binary data transfer mode
• -G <n>: send file in variable record length mode with n bytes maximum record length; overrides binary data transfer mode
• -H: send file in text mode; overrides binary data transfer mode
• -j <job ID, default: -1>: optional numeric job ID used for reference
• -k <file ID, default: -1>: optional numeric file ID used for reference
• [-a]: abort with returncode 18 if entry already exists
• [-I]: enqueue 'on hold', don't send file actively
• [-D <datestamp in format YYYYmmdd, i.e. 20081230>]: overriden datestamp of the file
• [-T <timestamp in format HHMMSSCCCC, i.e. 1435570001>]: overriden timestamp of the file

In order to enqueue an EERP message, the following parameters are available:

• -E: activate EERP mode (instead of file mode)
• -T <timestamp in format HHMMSSCCCC, i.e. 1435570001>
• -D <datestamp in format YYYYmmdd, i.e. 20081230>
• -z <destination SFID>
• -o <originator SFID>
• [-f <filename with absolute path> needed in OFTP2 sessions only]
• [-S <0|1> OFTP2 sign EERP (1) or not (0)
• [-U <ciphersuite> OFTP2 cipher suite (0, 1, 2...)]
• [-W <numeric value; default: 0>: EERP/NERP error code]

examples

• enqueue the file '/tmp/testfile' to partner 'c-works', using virtual filename 'testfile':

./os4xeq -p c-works -f /tmp/testfile -v testfile

• enqueue the file '/tmp/testfile' to partner 'c-works', using ENGDAT light virtual filename 'ENG061229153952001001':

./os4xeq -p c-works -f /tmp/testfile -v ENG061229153952001001

• enqueue the file same file '/tmp/testfile' to partner 'c-works', using ENGDAT light virtual filename 'ENG061229153952001001', but with increased priority (5):

./os4xeq -p c-works -f /tmp/testfile -v ENG061229153952001001 -u 5

• enqueue the file '/tmp/testfile' to partner 'c-works', using ENGDAT light virtual filename 'ENG061229153952001001', with comment 'this is a testcomment':

./os4xeq -p c-works -f /tmp/testfile -v ENG061229153952001001 -c "this is a testcomment"

• enqueue the file '/tmp/testfile' to partner 'c-works', using ENGDAT light virtual filename 'ENG061229153952001001', added passively, so partner must fetch the file (no active send):

./os4xeq -p c-works -f /tmp/testfile -v ENG061229153952001001 -P

Certificate exchange (the file parameter "-f /tmp/testfile" must point to any dummy file; the certificate request will be executed with the latest certificate configured in the OFTP2 partner settings):

• request certificate from OFTP2 partner 'c-works':

./os4xeq -p c-works -f /tmp/testfile -v ODETTE_CERTIFICATE_REQUEST

• send my certificate to OFTP2 partner 'c-works':

./os4xeq -p c-works -f /tmp/testfile -v ODETTE_CERTIFICATE_DELIVER

Enqueue an EERP to a given partner:

./os4xeq -E -p PARTNER_TESTNAME -v TESTFILE -T 1800652001 -D 20081012 -z DESTSFID -o ORIGSFID

Enqueue a signed OFTP2 EERP to a given OFTP2 partner, providing the received (decrypted, decompressed and verified native plain file), using cipher suite 2 for hashing:

./os4xeq -E -p PARTNER_TESTNAME -v TESTFILE -T 1800652001 -D 20081012 -z DESTSFID -o ORIGSFID -f /bin/bash -S 1 -U 2

Enqueue a signed OFTP2 NERP with reason code 34 ("File processing failed") to a given OFTP2 partner, providing the received (decrypted, decompressed and verified native plain file), using cipher suite 2 for hashing:

./os4xeq -E -p PARTNER_TESTNAME -v TESTFILE -T 1800652001 -D 20081012 -z DESTSFID -o ORIGSFID -f /bin/bash -S 1 -U 2 -W 34

os4xlic

This tool displays the OS4X ID, an installation specific hash value, which identifies this copy of OS4X.

input parameters

• -h: help text
• -I: display OS4X ID only (without headers)
• -v: display version information and exit

examples

localhost:~/tmp username$ ./os4xlic 
OS4X license tool v2.0

your OS4X ID is:
8b6c03222dc17af20d4c022d6cf92d502cb8d51b230467582b8d111a39e7b0bcv2

(all in one line)

localhost:~/tmp username$ ./os4xlic -I
8b6c03222dc17af20d4c022d6cf92d502cb8d51b230467582b8d111a39e7b0bcv2

os4x_licinfo

Display the information encoded in an OS4X license file.

input parameters

• -h: help text
• -C configfile: use given config file (default: /etc/os4x.conf)
• -f license file: use the given license file as input
• -d: display end date of validity
• -I: display licensed OS4X ID
• -p: display amount of licensed partners
• -a: display licensed functions
• -A: display licensed functions, as numeric value
• -v: display version information and exit

examples

localhost:~/tmp username$ ./os4x_licinfo -I
8b6c03222dc17af20d4c022d6cf92d502cb8d51b230467582b8d111a39e7b0bcv2

localhost:~/tmp username$ ./os4x_licinfo -f /opt/os4x/bin/license.key -d
20080331

os4xped

In order to administrate basic partner information in the OS4X database, this command line tool can be used from external programs (i.e. SWAN 2.x, DDX, etc.). The main key is the partner shortname which must be unique. If no partner exists for the given shortname it will be created. If exactly one partner entry exists for the given shortname it will be used for changing configuration entries. If multiple partner entries exist for the given shortname the program aborts.

input parameters

• -h: help text
• -C configfile: use given config file (default: /etc/os4x.conf)
• -s <partner shortname>: shortname of partner

all other parameters are optional:

• -l <partner longname>: long description of partner
• -a <partner SSID>: partner's SSID
• -b <partner SFID>: partner's SFID
• -c <partner password>: partner's password
• -d <my SSID>: my SSID
• -e <my SFID>: my SFID
• -f <my password>: my password
• -g <his hostname/ip address>: his TCP/IP address
• -p <his tcp/ip port>: his TCP/IP port

example

localhost:~/tmp username$ ./os4xped -s testshortname -a "O001300 NEW SSID" -b "O001300 NEW SFID" -g os4x.remotedomain.com -p 3317
OS4X partner edit v1.4
successfully inserted new company

os4xpoll

Connect to a given partner and retrieve downloadable files (if any are given by partner) or receive EERP messages. The OFTP direction implemented is "R" (for "receive") only. Sending files is not supported.

input parameters

• -p <partner shortname>
• -i <partner index (primary database key value)>
• [-a <alternative partner's SFID for authentification>]
• [-n]: no not daemonize
• -h: this help text
• -C <configfile>: use given config file (default: /etc/os4x.conf)
• -v: display version

Since OS4X release 2020-09-01, the following parameters are available:

• -c <certificate CSR index as alternative TLS client certificate>: use a given certificate from the cerificate requests as TLS client certificate and OFTP2 secure authentiication certificate.
• -T <overridden TCP/IP timeout in seconds>

examples

localhost:~/tmp username$ ./os4xpoll -v
OS4X poll version 2 build 20080513

localhost:~/tmp username$ ./os4xpoll c-works

localhost:~/tmp username$ ./os4xpoll -C /etc/os4x.conf -p c-works

localhost:~/tmp username$ ./os4xpoll -i 758

In order not to daemonize the process (i.e. to count received files via returncode):

localhost:~/tmp username$ ./os4xpoll -C /etc/os4x.conf -p c-works -n

os4xrd

The main OS4X receive daemon which is responsible for accepting OFTP sessions. This daemon starts several processes:

• os4xrd: the management process which manages all subsequent child processes
• os4xrd_tcpip: main receive process for incoming TCP/IP connections. After having accepted a connection, this processes creates a new child process:
  • os4xrd_tcpip_active: an active TCP/IP OFTP connection
• os4xrd_tcpip_tls: main receive process for incoming TLS secured TCP/IP connections. After having accepted a connection, this processes creates a new child process:
  • os4xrd_tcpip_active: an active TLS secured TCP/IP OFTP connection
• os4xrd_capi_[number]: main receive process for incoming ISDN connections. The number is the index value of the CAPI configuration row. After having accepted a call, this processes creates a new child process:
  • os4xrd_capi_[number]_active: an active CAPI OFTP connection

This behaviour in changed process names is not available on HP/UX!

input parameters

• -h: help text
• -C <configfile>: use given config file (default: /etc/os4x.conf)
• -f start forced
• -v: display version
• -i <serverID>: start as server with ID <serverID> (default: 0)

os4xsqd

The send queue daemon checks new entries in the send queue, trying to send them. During processing, the daemon starts the following processes:

• os4xsqd: the management process which manages all subsequent child processes:
  • os4xsqd_tcpip_active: an active OFTP connection process, running a TCP/IP connection
  • os4xsqd_tcpip_tls_active: an active OFTP connection process, running a TLS secured TCP/IP connection
  • os4xsqd_capi_active: an active OFTP connection process, running an ISDN connection

This behaviour in changed process names is not available on HP/UX!

input parameters

• -h: help text
• -C <configfile>: use given config file (default: /etc/os4x.conf)
• -f start forced
• -v: display version
• -i <serverID>: start as server with ID <serverID> (default: 0)

os4xupdate

Check the integrity and signature of an update file and execute it. Optionally run the configurable post event after execution.

Since OS4X release 20240122, no license is required to run this program.

input parameters

• -h: printf this help text
• -C <configfile>: use given config file (default: /etc/os4x.conf)
• -f <filename with absolute path>
• -V: print out version and exit

examples

./os4xupdate -f /opt/os4x/incoming/OS4X_UPDATE

./os4xupdate -C /usr/local/os4sx/os4x.conf -f /tmp/manually_received_update_file

shox

The OS4X shell. Start programs with parameters outside OS4X as if they were started inside OS4X events or other states.

input parameters

• -h: this help text
• -C <configfile>: use given config file (default: /etc/os4x.conf)
• -e <executable>: executable to be started
• -p <parameters>: parameters to give the executable
• -v|V: print out version and exit

examples

/opt/os4x/bin/shox -e set

/opt/os4x/bin/shox -C /usr/local/os4x/os4x.conf -e /bin/ls -p "-l /tmp"

os4x_check_lcapi

Check all locally installed CAPI controllers of the underlying Linux CAPI2.0 system. This binary is also used by the web interface in the section "CAPI", when scanning for new devices.

input parameters

• [-x: output in XML format]

examples

Human-readable mode:

os4xbox:~# /opt/os4x/bin/os4x_check_lcapi 
OS4X local CAPI check tool v1.0

Available controllers:                1

Checking controller 1:
Available channels per controller:    2
B1 protocol:                          0x11F
B2 protocol:                          0xB1B
B3 protocol:                          0xBF
B3 protocol X.25 available (OFTP ready)

XML mode:

os4xbox:~# /opt/os4x/bin/os4x_check_lcapi -x
<?xml version="1.0" encoding="UTF-8"?>
<OS4X_Brick_config>
<available_controllers>1</available_controllers>
<controller>
<number>1</number>
<index>0</index>
<channels>2</channels>
<b1_protocol>0x11F</b1_protocol>
<b2_protocol>0xB1B</b2_protocol>
<b3_protocol>0xBF</b3_protocol>
<b3_protocol_x25>1</b3_protocol_x25>
</controller>
</OS4X_Brick_config>

os4xsend

Send a single file with a given virtual filename to a defined partner.

input parameters

• -h: this help text
• -C <configfile>: use given config file (default: /etc/os4x.conf)
• -p <partner shortname> (mandatory)
• -f <file to send (absolute path)> (mandatory)
• -v <virtual filename> (mandatory)
• -a <alternative SFID originator>
• -b <alternative SFID destination>
• -s <alternative SSID originator>
• -t <alternative SSID destination>
• -d: daemonize (backgrounding process)
• -D <optional file description in OFTP2 session>
• -o: verbose output
• -V: print out version and exit
• [-F <n>]: send file in fixed record length mode with n bytes maximum record length; overrides binary data transfer mode
• [-G <n>]: send file in variable record length mode with n bytes maximum record length; overrides binary data transfer mode

examples

Send file "/opt/os4x/outgoing/testfile" as "TESTFILE" to partner "c-works":

/opt/os4x/bin/os4xsend -p c-works -f /opt/os4x/outgoing/testfile -v TESTFILE

os4xdebugd

The OS4X debug is an optional daemon which collects data from every running OS4X process. It saves the collected data in memory with a maximum size, rotating the log entries automatically (since it's a ring buffer). When an error occurs, it's quite handy to have the debug daemon running, because the debug daemon can produce an encrypted log file which contains information of value for debugging the behaviour. For producing such a log, the debug daemon binary must be started with parameter "d" or "-D":

input parameters

• -h: this help text
• -C <configfile>: use given config file (default: /etc/os4x.conf)
• -f: start forced
• -v: display version
• -d: dump log to OS4X temporary directory
• -D: dump log to /tmp (if everything else fails)

examples

Start the daemon:

/opt/os4x/bin/os4xdebugd

Start the daemon forced (i.e. after system crash or hardware reset):

/opt/os4x/bin/os4xdebugd -f

Start the debug daemon with an alternative configuration file:

/opt/os4x/bin/os4xdebugd -C /opt/os4x/os4x.conf

Dump a log file to the configured temporary directory:

/opt/os4x/bin/os4xdebugd -d

Dump a log file to /tmp (i.e. when the database is inaccessible and dumping to the configured temporary directory is not possible):

/opt/os4x/bin/os4xdebug -D

Configuration parameter

A configuration parameter exists to influence the size of the ring buffer. The parameter "os4xdebugd_max_bufferlength" is the amount of log lines the debug daemon manages. This is just a rough calculation, but a default value of 10000 leads to a memory consumption (and file size) of about 1MB. If this parameter doesn't exist a default of 10000 is assumed.

Behaviour

Beginning with the debug daemon version 2012-05-12, it reacts on signal 3 (SIGQUIT) in order to write an actual debug dump to OS4X's temporary directory.

os4x_dbupdate

The OS4X database schema updater identifies missing database table and columns and re-creates them. This may be helpful after a system crash, database recovery and system update.

input parameters

• -h: this help text
• -t: version test (without execution)
• -C <configfile>: use given config file (default: /etc/os4x.conf)

examples

Testing the actual database version against the binary version:

/opt/os4x/bin/os4x_dbupdate -t

Output:

Database version test succeeded: installed database is older that actual schema updater.

Running the database update process for creating missing tables and columns:

 /opt/os4x/bin/os4x_dbupdate

Output:

moving system logs older than 14 days to vault... 	done in 0 seconds
moving send logs older than 14 days to vault... 	done in 0 seconds
moving receive logs older than 14 days to vault... 	done in 0 seconds
moving xERP logs older than 14 days to vault... 	done in 0 seconds
moving event logs older than 14 days to vault... 	done in 0 seconds
checking must-have plugin groups... 	done
Configured openSSL binary is configured to '/opt/os4x/bin/openssl', running functionality check...
No change to openSSL configuration needed.
OS4X database is now up to date