OS4X Core configuration

Accessing configuration

OS4X stores its core configuration in one simple database table. The configuration can therefor be changed in two ways:

• using the comfortable web interface
• using a database client program to change the values manually.

Because of the quite non-understandable names of the configuration values, all configuration value names are listed in each block of configuration for manual editing.

web interface method

The OS4X web interface includes an entry in the left menu for the core configuration. Its name is "Configuration". The configuration web interface is segmentated into the following blocks:

• TCP/IP
• SSL/TLS
• ISDN
• Odette
• Directories
• Event scripts
• Daemon
• Partner table
• GUI niceup

Each block is accessible with a link in the head of the configuration panel. Also, each block is entitled with its name and a link to access the top of the form.

database method

The table "[tableprefix]configuration" (default: "os4x_configuration") contains two columns:

• name
• value

The column "name" is the name of the configuration which is affected.

The column "value" reflects the configuration value, limited to 255 characters.

All boolean values react that the a value of zero ("0") if false and all other values are true.

Configurable values

The following configuration parameters show the position in the web GUI, beginning in the top. Each configuration name as used in all binaries, web interface, scripts etc. are listed in each block and explained as needed.

TCP/IP

This block contains all basic TCP/IP parameters, such as port numbers, timeout values etc.

TCP/IP port of OFTP server

DB configuration name: tcp_port

This numeric value between 1 and 65535 describes the TCP/IP port the OFTP server is watching for incoming connections. The maximum of parallel incoming connections is limited by the operating system kernel and can be influenced by the kernel parameter "SOMAXCONN".

TCP/IP port of OFTP server (TLS)

DB configuration name: tcp_port_tls

This numeric value between 1 and 65535 describes the TCP/IP port the OFTP server is watching for incoming OFTP2 connections which are secured by TLS. The maximum of parallel incoming connections is limited by the operating system kernel and can be influenced by the kernel parameter "SOMAXCONN". This port must not be the same as the OFTP server port from above.

TCP/IP port of OS4X debug daemon

DB configuration name: debugd_port

This numeric value between 1 and 65535 describes the TCP/IP port the OFTP server is watching for debug output. Every OS4X program generates this output. The daemon collects this data and is able to dump this data in an encrypted file. This must not be the same as OFTP or OFTP 2 server ports.

TCP/IP timeout

DB configuration name: tcp_timeout

This numeric value defines the maxmimum number of seconds between two TCP/IP packages to arrive. If this value is too low you might get network disconnects, setting this value very high means that a network disconnect will be discovered very late.

TCP/IP OFTP maximum buffersize

DB configuration name: oftp_default_buffersize_tcpip

During the OFTP handshake, the maximum size of a data buffer will be commited. This value reflects the maximum size of such data buffers. The minimum value is 128, the maximum can be should not be over 65535 (because of TCP/IP packaging). The higher the value, the faster the data transfer rate will be (but it depends on the partner side). On unreliable connections, use the default value of 2048 bytes.

TCP/IP OFTP maximum credit count

DB configuration name: oftp_default_creditcount_tcpip

As the OFTP maximum buffersize, this value will be commited with the partner during a OFTP handshake. The number defines the amount of uncommited data buffers send to the receiver during file transfers. Increasing this value also increases the throughput. On unreliable connections you should use the default of 20. This is a different value than used for ISDN connections.

use receiving acceleration?

DB configuration name: oftp_tcpip_rec_acceleration

This technique is used to accelerate incoming TCP/IP connection by pre-sending the so-called "OFTP credits" (which are used for handshaking OFTP data buffers) during file transfers. If your partner doesn't like this type of acceleration (i.e. partners who use Seeburger products), you have to disable it. You also have the chance to define a row in the partner table to define partner based acceleration.

use send acceleration?

DB configuration name: oftp_tcpip_send_acceleration

Enabling this feature turns on code to ignore the first OFTP credit messages during file transfer. This tunes up transfer speed up to factor 100. The number of "ignored" OFTP credits is calculated dynamically via the agreed value of the buffersize during protocol handshake, based on a maximum TCP/IP package size of 60000 bytes (where 65536 bytes are possible). If you experience transfer aborts, disable this feature.

SSL/TLS parameters

For securing TLS sessions over TCP/IP networks (such as internet), you need to give some information about your local certificates. These information don't have to be the same as for file based security.

local certificate file & local certificate password

DB configuration name: tls_local_certificate & tls_server_cert_password

Absolute path to the OFTP server certificate (in PEM format) for OFTP over TCP/IP (TLS secured). If the certificate is password-protected, you may enter it in the password field.

local client certificate file & client certificate password

DB configuration name: tls_default_client_certificate & tls_client_cert_password

Absolute path to the OFTP server certificate (in PEM format) for OFTP over TCP/IP (TLS secured). If the certificate is password-protected, you may enter it in the password field.

root certificate file & root certificate path

DB configuration name: tls_root_certificate & tls_root_certpath

The root certificates are used to authentificate partners which have certificates of unknown signers. At least one of these fields must be filled (even if the root certificate path doesn't contain any root certificates). The certificates must be in PEM format.

Diffie-Hellman parameter files

DB configuration name: dh128_file, dh256_file, dh512_file & dh1024_file

These files (128bit, 256bit, 512bit and 1024bit) contain prime numbers, which are the basis for TLS encrypted connections. If the file is writable, or the file doesn't exist and the directory is writable, you can generate a new file from the web interface by using the link "Recalculate" or "Generate" in the web interface, which opens a new window which executes the command. Don't close this window until you can read the message "You can close this window now"!

Allow self-signed certificates

DB configuration name: oftpv2_allow_selfsigned_cert

Enabling this checkbox disables the rejection of incoming TLS connections which are secured via a self signed certificate. The default should be on.

Entropy file for random data

DB configuration name: tls_entropy_file

In order to use TLS, you have to specify a random data source. This is a kernel based character file (like "/dev/urandom" or "/dev/random"). If your operating system doesn't support such a random file (like AIX 5.1), you can generate such a file on your own (i.e. with the tool "ssh-rand-helper" from any openSSL installation). At least 256 bytes of random data must exist in this file.

ISDN parameters

Basic ISDN parameters for OFTP connections have to be defined here.

ISDN OFTP maximum buffersize

DB configuration name: oftp_default_buffersize_isdn

As the TCP/IP maximum buffersize (as mentioned above), this numeric value reflects the maximum size of a OFTP data buffer. It may result to problems if this is set to values higher than your ISDN controllers can use for maximum transfer size, which is limited by CAPI2.0 to 4096 bytes. The minimum is 128 bytes.

ISDN OFTP maximum credit count

DB configuration name: oftp_default_creditcount_isdn

Same as the TCP/IP maximum credit count, this numeric value reflects the number of OFTP data exchange buffers before a little handshake will be done by the OFTP protocol.

Odette parameters

Default OFTP parameters for authentifications are configurable here. If no special columns are defined in the partner table below, these values will be used.

my default SSID, my default SFID, my default OFTP password, change every partner entry

DB configuration name: default_ssid, default_sfid & default_password

These elements are only used for the web interface for creating new partners or for changing all partner values. If the checkbox is enabled, all partners in the partner table will get the new values for SSID, SFID and password on your side. If you don't configure columns in the partner table configuration below, these values are used for OFTP authentification.

Directories

In order to let OS4X know where to find directories and files, these values have to be defined.

data incoming directory

DB configuration name: incoming_directory

After successful file transfers (receiving), this directory defines where the incoming files will be stored. This directory must be on the same filesystem as the temporary directory (see below), otherwise you will get an error message in syslog (if enabled) that moving incoming files cannot be done. The filesystem must be dimensioned big enough to store a file with at most the maximum transfer size. I.e., if you receive a file of 200MB, you will need to have 200MB free on this filesystem, otherwise an error message will be sent to the partner (that the local filesystem is not big enough) and an entry to the receive log will be added.

data outgoing directory

DB configuration name: outgoing_directory

In order to enqueue a new file, the file selector of the web interface (in the send queue) will point to this directory first. Also, OS4X Enterprise uses this directory for outgoing files selected by a client.

temporary directory

DB configuration name: tmp_directory

During incoming file transfers, the file fragments will be stored in this directory. Keep in mind (as mentioned above) to set this directory to the same filesystem as the incoming directory. The filesystem must be dimensioned big enough to store a file with at most the maximum transfer size. I.e., if you receive a file of 200MB, you will need to have 200MB free on this filesystem, otherwise an error message will be sent to the partner (that the local filesystem is not big enough) and an entry to the receive log will be added.

database backup directory

DB configuration name: backup_directory

If you want to use the OS4X backup mechamism, you need to define a directory where the SQL dump files will be stored. This directory is needed for the scripts "os4xbackup" and "os4xrestore".

binary installation directory

DB configuration name: bin_directory

This directory points to your binary installation of OS4X. It also contains the license key, so if you receive a license error, first check the existence of this directory and the file "license.key" in it. This entry is also used for the web interface to start the daemons.

script installation directory

DB configuration name: script_directory

This directory points to your script installation of OS4X. It contains helpful scripts, such as database backup and restore scripts and maybe other useful tools. The OS4X web interface uses this definition.

absolute path to 'openssl'

DB configuration name: openssl_binary_path

OS4X uses openSSL as basis for all OFTP 2 file security functions. The configured binary must exist and be executable for the user running OS4X processes.

absolute path to 'rrdtool'

DB configuration name: rrdtool_binary_path

In order to use statistics, you have to define the path to „rrdtool“, the Round Robin database tool by Tobias Oetiker. The standard OS4X distribution contains a pre-compiled version which works within OS4X. If the file configured isn't executable, statistics are disabled. The program is used to create databases within OS4X binaries, push data in it and to display the results as graphical output in the web interface. The latest version of "rrdtool" can be found under http://oss.oetiker.ch/rrdtool/. On his website he has also Amazon wishlists, so if you want to support his great work, please donate some gifts.

RRDB data path

DB configuration name: rrdb_datapath

In this path, OS4X creates, stores, modifies and searches the files for statistics. The directory must be writable by the user running OS4X. If the path isn't writable or doesn't exists, statistics are disabled. For each partner, a file is generated for incoming transfer and for outgoing. The total consumption on the filessystem is about 315kB per partner.

absolute path to RRDtool TTF file

DB configuration name: rrdtool_font_path

The statistical overview needs a font file (as Truetype font). Without this font file, you won't get any textual information in the statistic graphs.

SQL lost messages file

DB configuration name: sql_lost_messages_file

If the configured MySQL server isn't reachable at any time, the SQL statements which are being sent to the MySQL server are logged into this file. If the file doesn't exists it will be created, so the directory must be writable for the user running OS4X. The file itself (if it exists) must also be writable by the user running OS4X.

MySQL dump tool

DB configuration name: mysqldump

As a useful tool from each MySQL distribution, the tool "mysqldump" is used in the OS4X backup script for doing its job.

Event scripts

First some words about the global behaviour of scripts:

event script usage

Every time the configuration of OS4X is checked by a binary (which is at start time or when processing the signal 1 - SIGHUP), the event script configuration is checked. If a script is non-existant and/or the execute permissions don't allow the execution of a configured script, it won't get executed. No warning will be printed out or logged somewhere.

event script sleep time

Sometimes it is very handy if the event scripts are started with a little lag. This can be especially interesting if the „end receive“ or „end send“ scripts are called very fast because of small transfer files (i.e. ENGDAT abstract file). If you experience problems with your EDI system (i.e. it doesn't catch all files), try to increase the appropriate value. Keep in mind that the OFTP session waits that time you configured the sleep time. Setting the values very high increases the risk of a disconnect if the remote site has very little timeouts configured! More than 5 seconds should not be normal!

start send script

DB configuration name: start_send_script & sleep_start_send_script

If a file is getting sent, this script or program will be started with the documented parameters.

end send script

DB configuration name: end_send_script & sleep_end_send_script

If a file has finished (successfully or not) sending, this script or program will be started with the documented parameters.

xERP script

DB configuration name: xerp_script & sleep_xerp_script

If an EERP or NERP (OFTP 2 only) message is received, this script will be started. OS4X tries to find a send queue entry which conforms to the given parameters in order to set the values for comment, absolute path etc. If no send queue entry can be found that matches the given parameters in the EERP or NERP message, the script won't be executed. This script receives the same parameters as the end send script script.

start receive script

DB configuration name: start_receive_script & sleep_start_receive_script

If a file is getting received, this script or program will be started with the documented parameters.

end receive script

DB configuration name: end_receive_script & sleep_end_receive_script

If a file has finished (successfully or not) receiving, this script or program will be started with the documented parameters.

start session script

DB configuration name: start_session_script & sleep_start_session_script

After a positive OFTP handshake, this script or program will be started with the documented parameters.

end session script

DB configuration name: end_session_script & sleep_end_session_script

After a positive OFTP session, this script or program will be started with the documented parameters.

send queue entry blocked script

DB configuration name: blocked_script & sleep_blocked_script

If a send queue entry gets blocked (i.e. wrong authentification, unsupported virtual filename at the remote site, connection problems), this scripts will be started. If more than one entry for a partner gets blocked, each send queue entry will start its own blocked script.

debug daemon log script

DB configuration name: os4xdebugd_log_script

After a debug log has been written, this script will be started. This can be the case when asking for a debug log interactively (or with starting the appropriate program manually) or, if configured, when automatically created debug logs are written.

license script & trigger level

DB configuration name: license_script & license_script_hwm

This script will be started after a configurable trigger level (in percent) is exceeded. Its main porpuse is to inform a responsible person that a new license should be obtained or other actions should be taken.

Daemon parameters

The behaviour of all binaries and OS4X programs can be influenced here.

time slice for send queue daemon

DB configuration name: os4xsqd_sleep_time

The send queue daemon „os4xsqd2“ waits this amount of seconds before looking at the send queue table and react as needed (send one more entry, wait more time etc.).

time slice for receive daemon

DB configuration name: os4xrd_sleep_time

The receiving daemon „os4xrd2“ waits this amount of seconds before looking at the configuration table and react as needed (wait more time or stop itself).

delete send queue entries

DB configuration name: delete_after_transfer

This checkbox defines if the send queue table entries should be deleted (not the files itself, only the entry!) after a successful send. (If you need to delete the file itself, you should use the end send script, which gets the absolute filename as a parameter).

let all files of send queue be fetchable

DB configuration name: fetch_all_from_remote

Since polling is supported from remote systems, you can define files to be pollable. If you enable this checkbox, all files in your send queue which are in state of "new in queue" and "ready for remote fetch" will be sent in an OFTP session to the partner (otherwise, only entries "ready for remote fetch" are fetchable).

overwrite existing incoming files

DB configuration name: os4xrd_overwrite

If the incoming file exists in the "incoming directory", you can define to overwrite it. Otherwise, the partner will receive an error message saying that the local file already exists. (this might be useful for partners who don't like to reiceive an EEPR [end-to-end- response] message right after a successful filetransfer).

archive received xERP messages & archive sent xERP messages

DB configuration name: oftpv2_archive_received_xerp & oftpv2_archive_sent_xerp

It may be useful archive positive and/or negative end-to-end responses. These xERP messages can be seen as acknowledgements from the partner (received xERP) or from yourself (sent xERP). The web interface contains a archive viewer on the left hand: "xERP log". This feature may be needed in some countries for legal issues.

use syslog

DB configuration name: use_syslog

If you turn on this checkbox, major errors will be logged to the server's syslog facility with the severity LOG_ERR. Major errors are table misconfigurations or process dependant messages (fork failures, memory allocation problems etc.).

default maximum send tries for send queue daemon

DB configuration name: os4xsqd_max_tries

The send queue daemon "os4xsqd2" will try to send one or all entries this amount of times. After this amount of unsuccessful tries, one or all send queue entries for that partner will be blocked (which will also get logged into the send log). All entries for a partner get blocked, if a connection problem occurs (i.e. invalid SSID/SFID or password, no physical connection to partner, wrong ISDN number or TCP/IP address etc.). One entry will be blocked if the partner doesn't accept this file. The other files are not affected by that error (i.e. wrong virtual filename, wrong alternative SFID of originator or destination).

additional sleeping time for send queue daemon & additional sleeping time factor for send queue daemon

DB configuration name: os4xsqd_add_time & os4xsqd_add_time_factor

You can influence the time the send queue daemon „os4xsqd2“ will sleep before it tries to send an send queue entry. The formula for calculating the additional sleep is as follows:

(add. waiting time) = (connect try)*(add. sleeping time)*(add. sleeping time factor) 

progress bar refresh time

DB configuration name: progressbar_refresh

OS4X will update all file transfer progress information after this value (in seconds). Because it is database driven, some MySQL server will crash if you have too many connects to a database in a very short time (which could occur if you transfer very little files with a combination of a small exchange buffer size). If you experience problems with your database server, try increasing this value.

default maximum parallel send processes

DB configuration name: default_max_sendq_sendings_per_partner

You can define the amount of parallel sending processes globally here. There is also a definable column in the partner table (see below) to set this value on a per-partner base. If you don't have such a column, this default value will be used.

allow unsecure OFTP 2 authentification

DB configuration name: oftpv2_allow_unsecure_auth

If an OFTP 2 partner is requested to use OFTP 2 authentification but he doesn't support this feature, you may allow to authentificate this partner with the OFTP 1 methods by enabling this checkbox. If you insist to use OFTP 2 authentification, disable the checkbox, so the partner will receive an error message that OFTP 2 secure authentification is needed.

delete temporary created files of OFTP 2 session

DB configuration name: oftpv2_delete_temp_created_files

OS4X creates temporary files by enqueueing files to the send queue or by directly sending a file to an OFTP 2 partner (if the partner is configured to use signing, compression and/or encryption). These temporary files can be deleted by OS4X automatically, but you may also want to keep them for later archiving.

disable database schema check

DB configuration name: disable_check_os4x_tables

OS4X checks the database schema with every start of any OS4X binary program. This is very useful for verifying that the OS4X database tables are really up to date. If any table doesn't exists or a column is missing OS4X will try to create the item. The database user therefore needs privileges to create and modify the schema. Leave this checkbox disabled if you want to be on the safe side. Enable the checkbox to disable the schema checks and updates if you encounter database server problems or your database user has no privileges to modify the database.

local character set

DB configuration name: oftpv2_original_charset

OFTP 2 supports UTF-8 formatted information and error messages within the protocol and also extended virtual filenames (up to 999 bytes of UTF-8 formatted text). To translate the UTF-8 text into your local character set and to translate command line interaction from your local character set to UTF-8, you have to define your local character set here. If your local character set isn't listed here, you can define it in the database (table: "os4x_configuration") manually by entering the character set descriptor in the line where „name“ is "oftpv2_original_charset". All character sets which are supported by "iconv" are supported by OS4X. You get a list of supported character sets on the command line with the program:

iconv -l

if installed.

illegal characters for virtual filenames

DB configuration name: illegal_virt_filename_chars

In order to reject the receipt of files with irregular characters in its names, you can define a list of characters which are not allowed. If you keep this list empty, all files are accepted. If any of the configured characters is found in the announced virtual filename, the file is rejected and the partner receives the message "illegal character in virtual filename".

enable CAPI keep-alive monitor

DB configuration name: capi_check_alive_monitor

In order to use a Brick R4x00 or above, you have to enable this feature. Also, if you don't want to watch for OS4X after a reboot of the Brick device, enable this feature.

enable OFTP message checker

DB configuration name: oftp_message_checker

To secure your server, an OFTP message checker examines each transfered package for validity. This suppresses protocol attacks from remote and helps to avoid NULL pointer exceptions and other well-known attacks.

send queue entry status after abort

DB configuration name: sendq_entry_status_after_abort

You can define the status of a send queue entry after manual abort here. It may be useful to avoid a race between an administrator and the send queue daemon if he aborts the file transfer but the send queue daemon grabs it afterwards because the time slice has taken account. Valid options are "new in queue", "successfully sent", "blocked" and "ready for remote fetch".

enable script logging

DB configuration name: enable_script_logging

Enabling this feature logs all script calls, parameters, returncodes and output to the script logs. In the web interface, you can take a look at the script logs with the link „Script log“. In this interface, you can also restart event scripts (even if they have changed in the configuration: you can then execute the original or the new one, depending on executability of the script file).

enable statistics & RRDtools refresh time

DB configuration name: enable_statistics & rrd_refresh

As configured above with the RRDtool paths and directories, you have the possibility to activate or deactivate the scripting functionality here. The statistics contain the average transfer speed of a partner (incoming and outgoing as separate databases). If any of the above configured RRDtool path or binary is unavailable, scripting is disabled, even if you enable it here. The refresh time is the time is seconds when statistical data is transfered into the Round Robin database. This time period depends also on the database configuration of the RRDB and is closely dependant from the creation process which is intergrated into OS4X (if an RRDB file doesn't exist). The default of 10 seconds should not be changed!

append timestamp to received file

DB configuration name: rec_append_timestamp_to_filename

Some partners may send you files with the same virtual filename, but different timestamps. In order to receive these files properly, an appendix is added to the filename containing the announced timestamp of the file. This also helps to receive the same file from different partners at the same time. Beware: the timestamp syntax has changed from OFTP 1 to OFTP 2!

OFTPv1: Don't wait for EERP message

DB configuration name: oftpv1_dont_wait_for_eerp

The normal behaviour of a send queue item is as follows:

• new in queue: waiting for transfer
• taken by send queue: session active, waiting for transfer
• send in progress: active transfer
• waiting for remote acknowledge: waiting for EERP or NERP from partner
• successfully sent: partner acknowleged file (entry may be deleted if configured)

If an partner doesn't send an EERP message, the send queue entry will exist forever. In order to avoid this, the send queue entry may get the status „successfully sent“ after successful send by enabling this checkbox (and may be deleted if the above checkbox „delete send queue entries“ is enabled). Beware: the xERP scripts won't be executed any more because no send queue entry will be found matching the parameters given in any EERP or NERP message. This feature just affects OFTP v1 partners, not OFTP 2!

is OS4X Enterprise installed?

DB configuration name: os4x_enterprise

If you enable this checkbox, the web interface expands its funtionality needed to administrate OS4X Enterprise, an enhanced version of OS4X. Disabling this checkbox turns OS4X into its default configuration of OS4X Core. If you are interested in features of OS4X Enterprise, contact your software dealer or write an email to info@os4x.com .