Difference between revisions of "OS4X Core installation"

From OS4X
Jump to navigation Jump to search
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
== Automatic installer (.sh) ==
 +
Download the appropriate "automatic installer" package for your platform, supported database and ISDN connectivity. It will have a filename ending with ".sh", i.e.:
 +
os4x3_full_pe_Linux-x86-MySQL.sh
 +
Change the permissions of the downloaded file in order to make it executable:
 +
chmod 755 os4x3_full_pe_Linux-x86-MySQL.sh
 +
Then, start this automatic installer:
 +
./os4x3_full_pe_Linux-x86-MySQL.sh
 +
 +
The installer will ask you several questions:
 +
*temporary directory (for extraction of files)
 +
*base installation directory, which is the basis for the following directories:
 +
**binary installation directory
 +
**scripts directory
 +
**database backup directory
 +
**data incoming directory
 +
**outgoing data directory
 +
**OS4X's own temporary directory
 +
**RRDB directory (for statistical data, about 300kB per partner)
 +
*web interface directory
 +
 +
In case of a MySQL database connection, the server parameters will be asked for, given the database name will be created and a user added to MySQL.
 +
 +
The global configuration file '/etc/os4x.conf' will be generated automatically.
 +
 
== TAR Package ==
 
== TAR Package ==
Unpack the provided tar archive file for your platform. You get the following directory  
+
Unpack the provided TAR archive file for your platform, database and ISDN connectivity. You get the following directory structure (limited to the most important):  
structure:  
+
<pre>
 
+
|-- apache
dist
+
|-- images
|-- apache  
+
|  |-- os4x
`-- images  
+
|  `-- os4xapi
|  `-- sounds
+
|-- etc
|-- etc  
+
|-- opt
|-- opt  
+
|  `-- os4x
|  `-- os4x  
+
|      |-- ComSecure
|      |-- backup  
+
|      |-- backup
|      |-- bin  
+
|      |-- bin
|      |-- cert  
+
|      |-- bots
|      |-- incoming  
+
|      |-- cert
|      |-- outgoing  
+
|      |-- incoming
|      |-- rrd  
+
|      |-- outgoing
|      |-- scripts  
+
|      |-- plugins
|      `-- tmp  
+
|      |-- rrd
`-- sql
+
|      |-- scripts
 +
|      `-- tmp
 +
|-- os4xapi
 +
|-- sql
 +
`-- webaccess5
 +
</pre>
  
 
== Filesystem directories ==
 
== Filesystem directories ==
Line 24: Line 53:
  
 
=== backup ===
 
=== backup ===
In this directory, backup files of the MySQL database can be stored. The scripts [[OS4X Core administrative scripts#os4xbackup|os4xbackup]] and [[OS4X Core administrative scripts#os4xrestore|os4xrestore]] use this directory.  
+
In this directory backup files of the MySQL database can be stored. The scripts [[OS4X Core administrative scripts#os4xbackup|os4xbackup]], [[OS4X Core administrative scripts#os4xrestore|os4xrestore]] and [[OS4X_Core_administrative_scripts#os4x_archive.sh|os4x_archive.sh]] use this directory.
  
 
=== bin ===
 
=== bin ===
 
The binaries of the installation are stored here. The directory must at least contain the following binaries:  
 
The binaries of the installation are stored here. The directory must at least contain the following binaries:  
*os4xeq2 – program to enqueue files into the send queue  
+
*os4xeq3 – program to enqueue files into the send queue  
*os4xped2 – program to edit partner entries in the database  
+
*os4xped3 – program to edit partner entries in the database  
*os4xrd2 – the receiving daemon  
+
*os4xrd3 – the receiving daemon  
*os4xsqd2 – the send queue daemon  
+
*os4xsqd3 – the send queue daemon
  
 
=== cert ===
 
=== cert ===
Line 53: Line 82:
  
 
== Notes about upgrades ==
 
== Notes about upgrades ==
If you upgrade from an older OS4X version, you will see that the names of the binaries have changed. Some new binaries are new, others (like „os4xeq“) have a new name („os4xeq2“). A symbolic link is created to support the complete web interface for the older and the newer OS4X version. The web interface calls all binaries without the appendix „2“, so without the links (i.e. „os4xeq“ -> „os4xeq2“, „os4xsqd“ -> „os4xsqd2“ and so on), the web interface will display errors.
+
If you upgrade from an older OS4X version, you will see that the names of the binaries have changed. Some new binaries are new, others (like „os4xeq“) have a new name („os4xeq3“). A symbolic link is created to support the complete web interface for the older and the newer OS4X version. The web interface calls all binaries without the appendix „3“, so without the links (i.e. „os4xeq“ -> „os4xeq3“, „os4xsqd“ -> „os4xsqd3“ and so on), the web interface will display errors.
  
 
== MySQL ==
 
== MySQL ==
Line 73: Line 102:
 
''(Color explanation: green → database name; blue → username; red → password) ''
 
''(Color explanation: green → database name; blue → username; red → password) ''
  
The user must get all available MySQL permission in this database, because internal upgrade mechanism (as described in the "Advanced administration documentation") will try to extend or modify the database schema! OS4X supports MySQL databases from version 3.23 up to the latest MySQL version (which is 5.0 and 5.1beta when creating this document). Since MySQL version 4.x, the password hashing algorithm in the database server has changed. Because OS4X supports also older MySQL server versions, it uses an older client protocol than your MySQL server provides. In order to use your prefered MySQL server version anyway, you can modify the created MySQL user. If you experience any problems when starting OS4X processes and Syslog contains the message „Client does not support authentication protocol requested by server; consider upgrading MySQL client“, you have two options:  
+
The user must get all available MySQL permission in this database, because internal upgrade mechanism (as described in the "Advanced administration documentation") will try to extend or modify the database schema! OS4X supports MySQL databases from version 3.23 up to the latest MySQL version (which is 5.0 and 5.1beta when creating this document). Since MySQL version 4.x, the password hashing algorithm in the database server has changed. Because OS4X supports also older MySQL server versions, it uses an older client protocol than your MySQL server provides. In order to use your prefered MySQL server version anyway, you can modify the created MySQL user. If you experience any problems when starting OS4X processes and Syslog contains the message "'''Client does not support authentication protocol requested by server; consider upgrading MySQL client'''", you have two options:  
 
*start your MySQL daemon with the option "<code>--old-passwords</code>" (as documented on the MySQL website http://dev.mysql.com/doc/refman/5.0/en/old-client.html)  
 
*start your MySQL daemon with the option "<code>--old-passwords</code>" (as documented on the MySQL website http://dev.mysql.com/doc/refman/5.0/en/old-client.html)  
 
*refresh your OS4X user in the database with an old-hashing algorithm password by doing this:  
 
*refresh your OS4X user in the database with an old-hashing algorithm password by doing this:  
Line 86: Line 115:
  
 
== Main configuration ==
 
== Main configuration ==
Copy the main configuration file os4x.cfg from the distribution directory  
+
Copy the main configuration file <code>os4x.cfg</code> from the distribution directory  
 
  dist/etc/os4x.conf
 
  dist/etc/os4x.conf
to a path where you want (default: "/etc/os4x.conf"). Then, configure the appropriate variables in this file. A sample configuration file looks like this:  
+
to  
 +
/etc/os4x.conf
 +
Then, configure the appropriate variables in this file. A sample configuration file looks like this:  
 
  DB_HOST=localhost  
 
  DB_HOST=localhost  
 
  DB_USER=os4x  
 
  DB_USER=os4x  
Line 96: Line 127:
 
  # DB_PORT=3306  
 
  # DB_PORT=3306  
 
  TABLEPREFIX=os4x_  
 
  TABLEPREFIX=os4x_  
 +
# SERVERID=0
 +
MYSQLCLIENT=/usr/bin/mysql
 +
 
Lines with a hash ("<code>#</code>") at the beginning of a line are interpreted as a comment. The variable  
 
Lines with a hash ("<code>#</code>") at the beginning of a line are interpreted as a comment. The variable  
 
  DB_PORT
 
  DB_PORT
Line 101: Line 135:
  
 
== Web interface ==
 
== Web interface ==
For using the web interface, you need a webserver (Apache prefered) with PHP4 or newer support (PHP5 is also successfully tested). The directory apache in the distribution contains the complete web interface and needs to be copied to a directory somewhere under the document root directory (refer to your local installation). For example, on most linux distributions the document root directory is placed under "<code>/var/www/</code>". For simple administration,  you should copy recursively the OS4X apache directory somewhere under that directory into a new one.
+
The web interface communicates to the OS4Xapi, which expects the configuration file located in
cp -R apache /var/www/os4x/
+
/etc/os4x.conf
To configure the web interface to use the specific MySQL database (and the complete OS4X configuration in it), you have to edit the file "database.inc.php" in the web interface directory (i.e. "/var/www/os4x/database.inc.php"). A sample head output of that file looks like this:
+
If you need a different location, please contact support@os4x.com.
<pre>
 
<?php
 
$config_type="file";
 
// $config_type="direct";
 
$config_file="/etc/os4x.conf";
 
// confguration part for direct configuration: just uncomment the
 
following 5 lines and change values as needed
 
// $mysql_host = "localhost:3306:/tmp/mysql.sock";
 
// $mysql_user = "os4x";
 
// $mysql_password = "os4x";
 
// $DBName = "os4x";
 
// $tableprefix="os4x_";
 
</pre>
 
 
 
Lines beginning with "<code>//</code>" are comments. Because you can install multiple instances of OS4X on one machine, you have either to define valid configuration file (by setting "config_type" to "file" and "<code>config_file</code>" to the approriate absolute file position) or by setting all MySQL parameters manually (by setting "<code>config_type</code>" to "<code>direct</code>" and setting the variables <code>$mysql_host</code>, <code>$mysql_user</code>, <code>$mysql_password</code>, <code>$DBName</code> and <code>$tableprefix</code> as needed (dont forget to remove the "<code>//</code>" comment characters!).  
 
The "<code>normal</code> configuration uses the "<code>file</code> method by pointing to an OS4X configuration file.
 
  
 
== License key ==
 
== License key ==
Line 128: Line 146:
  
 
your OS4X ID is:
 
your OS4X ID is:
ad9e4595509be1c9558491ed5fa1b79e55d58f20ca7f4311bcc11e8209b3c80bv2
+
4149155fba54270581d695301504346ed19960172c112bf258ece6d681320b8av3cmrcl
  
 
(all in one line)
 
(all in one line)
 
</pre>
 
</pre>
After having received a valid license file („license.key“) either via software vendor or emergency key, copy it in the binary installation directory. Just copy the file with keeping the original filename. The binary installation directory is where all OS4X programs are located (i.e. "</code>/opt/os4x/bin/</code>"). This directory depends on your configuration (see below).
+
After having received a valid license file ("<code>license.key</code>") either via software vendor or emergency key, copy it in the binary installation directory. Just copy the file with keeping the original filename. The binary installation directory is where all OS4X programs are located (i.e. "<code>/opt/os4x/bin/</code>"). This directory depends on your configuration.
 +
 
 +
 
 +
 
 +
 
 +
'''Congratulations, you are now ready to continue with your [[OS4X Core configuration|OS4X configuration]] by surfing with your favorite web browser to the OS4X's web interface (located in the configured position, see above).'''

Latest revision as of 09:40, 21 March 2017

Automatic installer (.sh)

Download the appropriate "automatic installer" package for your platform, supported database and ISDN connectivity. It will have a filename ending with ".sh", i.e.:

os4x3_full_pe_Linux-x86-MySQL.sh

Change the permissions of the downloaded file in order to make it executable:

chmod 755 os4x3_full_pe_Linux-x86-MySQL.sh

Then, start this automatic installer:

./os4x3_full_pe_Linux-x86-MySQL.sh

The installer will ask you several questions:

  • temporary directory (for extraction of files)
  • base installation directory, which is the basis for the following directories:
    • binary installation directory
    • scripts directory
    • database backup directory
    • data incoming directory
    • outgoing data directory
    • OS4X's own temporary directory
    • RRDB directory (for statistical data, about 300kB per partner)
  • web interface directory

In case of a MySQL database connection, the server parameters will be asked for, given the database name will be created and a user added to MySQL.

The global configuration file '/etc/os4x.conf' will be generated automatically.

TAR Package

Unpack the provided TAR archive file for your platform, database and ISDN connectivity. You get the following directory structure (limited to the most important):

|-- apache
|   |-- images
|   |-- os4x
|   `-- os4xapi
|-- etc
|-- opt
|   `-- os4x
|       |-- ComSecure
|       |-- backup
|       |-- bin
|       |-- bots
|       |-- cert
|       |-- incoming
|       |-- outgoing
|       |-- plugins
|       |-- rrd
|       |-- scripts
|       `-- tmp
|-- os4xapi
|-- sql
`-- webaccess5

Filesystem directories

The created directory structure under "/opt" shows a suggestion for a standard installation. All directories will get defined via web interface, so keep in mind that the names can change. An explanation for each directory is as follows:

backup

In this directory backup files of the MySQL database can be stored. The scripts os4xbackup, os4xrestore and os4x_archive.sh use this directory.

bin

The binaries of the installation are stored here. The directory must at least contain the following binaries:

  • os4xeq3 – program to enqueue files into the send queue
  • os4xped3 – program to edit partner entries in the database
  • os4xrd3 – the receiving daemon
  • os4xsqd3 – the send queue daemon

cert

Global certificates, needed for resolving certificate chain resolution, are stored in this directory.

incoming

Incoming files which get successfully transfered by os4xrd get placed here. This should be an own filesystem. It must also be on the same filesystem as the directory „tmp“ (see below). The user running the OS4X processes must have read, write and execute permissions on that directory. For easy administration, set permissions to 777 (a+rwx).

outgoing

For availability reasons, we suggest to use an own filesystem for outgoing files. The send queue daemon can send every file available on the system.

rrd

Statistical files (like RRDtool database files) are stored in this directory. Per partner about 320kB of data is needed.

scripts

Event scripts are stored in this directory by default. These scripts are called whenever a session is started or ended, files start to transfer or the end of transfer is reached.

tmp

Temporary files like files during the receiving process are stored in this directory. After successful transfer they are moved into the incoming directory. Keep in mind to set the size to the maximum file size you can receive because these files will be temporarily stored into this directory. This directory must be on the same filesystem as incoming, otherwise the moving process cannot be done. The user running the OS4X processes must have read, write and execute permissions on that directory. For easy administration, set permissions to 777 (a+rwx).

Notes about upgrades

If you upgrade from an older OS4X version, you will see that the names of the binaries have changed. Some new binaries are new, others (like „os4xeq“) have a new name („os4xeq3“). A symbolic link is created to support the complete web interface for the older and the newer OS4X version. The web interface calls all binaries without the appendix „3“, so without the links (i.e. „os4xeq“ -> „os4xeq3“, „os4xsqd“ -> „os4xsqd3“ and so on), the web interface will display errors.

MySQL

Either you use a graphical interface for managing the database settings (i.e. phpMyAdmin or MySQLCC), or you can use the commandline tools provided by your local MySQL installation.

The MySQL command line client should be called by a user who has administrative rights on the MySQL database (mostly "root"), otherwise use the command line parameters "-u" and "-p" to provide a valid MySQL user (with password, if needed) which has the administrative permissions.

Create MySQL database

Choose a name for your database where OS4X stores its information. In this installation example, we use the name "os4x" as the database name.

Commandline call:

mysqladmin [-uroot] [-p] create os4x 

Create MySQL user

Now, create a MySQL user who gets full permissions on this database. We use "os4x" for simplicity.

echo "GRANT ALL ON os4x.* TO os4x@localhost IDENTIFIED BY 'os4x';" | mysql [-uroot] [-p] 
echo "FLUSH PRIVILEGES;" | mysql [-uroot] [-p] 

(Color explanation: green → database name; blue → username; red → password)

The user must get all available MySQL permission in this database, because internal upgrade mechanism (as described in the "Advanced administration documentation") will try to extend or modify the database schema! OS4X supports MySQL databases from version 3.23 up to the latest MySQL version (which is 5.0 and 5.1beta when creating this document). Since MySQL version 4.x, the password hashing algorithm in the database server has changed. Because OS4X supports also older MySQL server versions, it uses an older client protocol than your MySQL server provides. In order to use your prefered MySQL server version anyway, you can modify the created MySQL user. If you experience any problems when starting OS4X processes and Syslog contains the message "Client does not support authentication protocol requested by server; consider upgrading MySQL client", you have two options:

echo "SET PASSWORD FOR 'os4x'@'localhost'= OLD_PASSWORD('os4x');" | mysql [-uroot] [-p] 

(if the above user information and password were used)

echo "FLUSH PRIVILEGES;" | mysql [-uroot] [-p]

Import MySQL tables

Use the provided file „os4x.sql“ as the data source for the mysql import process:

mysql [-uroot] [-p] os4x < os4x.sql 

Where the first "os4x" is the database name for your installation (see above).

Main configuration

Copy the main configuration file os4x.cfg from the distribution directory

dist/etc/os4x.conf

to

/etc/os4x.conf

Then, configure the appropriate variables in this file. A sample configuration file looks like this:

DB_HOST=localhost 
DB_USER=os4x 
DB_PASS=os4x 
DB_NAME=os4x 
# DB_SOCKET=/var/lib/mysql.sock 
# DB_PORT=3306 
TABLEPREFIX=os4x_ 
# SERVERID=0
MYSQLCLIENT=/usr/bin/mysql

Lines with a hash ("#") at the beginning of a line are interpreted as a comment. The variable

DB_PORT

is only used for remote MySQL databases. The tableprefix defines the prefix for all internally fix names of tables, not the partner table as defined in the basic configuration (the default of "os4x_" should not be changed if you haven't modified all table names manually!).

Web interface

The web interface communicates to the OS4Xapi, which expects the configuration file located in

/etc/os4x.conf

If you need a different location, please contact support@os4x.com.

License key

In order to run OS4X you need a valid license key. To obtain a key you can order a two week test license through the website of OS4X or buy a full license (also see the homepage or ask a reseller). In any case, you need to know your OS4X ID, which can be displayed with the tool os4xlic. A sample output of this program looks like this:

root@localhost:/opt/os4x/bin> ./os4xlic 
OS4X license tool v2.0

your OS4X ID is:
4149155fba54270581d695301504346ed19960172c112bf258ece6d681320b8av3cmrcl

(all in one line)

After having received a valid license file ("license.key") either via software vendor or emergency key, copy it in the binary installation directory. Just copy the file with keeping the original filename. The binary installation directory is where all OS4X programs are located (i.e. "/opt/os4x/bin/"). This directory depends on your configuration.



Congratulations, you are now ready to continue with your OS4X configuration by surfing with your favorite web browser to the OS4X's web interface (located in the configured position, see above).