Next Previous Contents

2. How to install the CLX software on your system

The installation of the CLX software requires some knowledge of Linux and Unix in general. It is not an easy task.

Here's a checklist for you:

If you can say yes to all of the above, you are prepared to install CLX. If not, you better get yourself a book about Linux/Unix and play around with your system to become familiar. This may take some time (weeks, months).

This version of CLX is glibc-based. That means, no longer will it require you to make symbolic links and find a special version of libc.so.5 as it used to be in previous versions. However, CLX will no longer run on an old libc.5-based system.

For CLX to run, the following software packages must be installed on your system.

From CLX version 5.00 Postgres is no longer part of the CLX distribution. We used to have Postgres along with CLX for many years but lately Linux distributions come with rather current Postgres packages and so the hassle to remove a pre-installed Postgres from a new Linux system has become bigger than the benefits of providing Postgres along with CLX. So the decision was made to leave it out and you have to install it for yourself.

You need at least Postgres version 6.5 tp run with CLX 5.00.

2.1 Users in /etc/passwd

CLX needs one new user in your /etc/passwd:

User            Group   Home Directory              UID
---------------------------------------------------------
clx_us          users   /usr/local/clx              101
---------------------------------------------------------

It is necessary to add the clx_us before you unpack the software, so the files will have correct ownership and permissions. The UID is chosen randomly, it does not really matter.

2.2 Unpacking the software

The CLX software comes in a single huge .tgz file. The file should be installed as follows:

# cd /
# tar xvzf clx_XXX.tgz

This will unpack the CLX software in the directory /usr/local/clx. You will need approximately 5 MB of disk space to install it.

You have now completed step one of the CLX installation! Fine!

2.3 A new Kernel

You need a Linux kernel of version 2.0.36 with the following drivers/components:

Earlier or later kernel versions may or may not work. Earlier versions required patches (called ax25-module14f or the like). We are currently using 2.0.36 at DB0CLX. The 2.0.36 kernel sources come with the AX.25 drivers in place, but they must be activated.

Currently I am not aware of how the 2.2.x kernels work with AX.25. There used to be some problems which may be fixed now.

If you got to compile a new kernel, please consult your Linux distribution manual. It is usually a sequency of "make config, make dep, make".

Congratulations! You have now finished the second step of the CLX installation procedure.

2.4 Testing the AX.25 driver

CLX does not require you to use the AX.25 kernel driver. If you wish to do so, you should now make sure everything works. If not you may skip this section and continue with the next one.

To check whether the newly created kernel driver is working we will make some tests. First you should get the most recent AX.25 utility package. This package contains programs which will allow you to make use of the kernel drivers. Without them, the drivers are just sitting in the kernel doing nothing.

The old version ax25-utils-2.0.12c.tar.gz dated December 28, 1996 is no longer supported and should not be used any more. The current utilities are in a file called ax25-2.1.42a.tgz available from ftp://ftp.pspt.fi/pub/ham/packet/linux/ax25.

Grab them, compile them and install them in the default directories using make install.

If you are using a 2.1 kernel, you could just go and use the new utilities without patching the kernel. There is some information regarding this subject in the AX25-HOWTO document, available, for instance, from http://sunsite.unc.edu/mdw/HOWTO/AX25-HOWTO.html.

Now we must configure ax25d. Go to the /dev directory and make a soft link from the ttyS? where your TNC is connected to /dev/tnc:

# cd /dev
# ln -s ttyS0 tnc

Switch your TNC into KISS mode. With my TNC2 clone running WA8DED firmware, I use the following command:

# echo -e "\015\015\033@K" > /dev/tnc

The TNC should signal the transition into KISS mode by flashing the CON and STA LEDs three times. After that you should observe that the CON LED keeps flickering very hectically. This is a good sign! If it doesn't, your TNC is probably not in KISS more or it behaves differently.

Now edit the file /etc/ax25/axports. You must specify your ``outgoing'' callsign for the different devices you have. Each TNC device gets one line in that configuration file. I have just one TNC connected so my file contains only a single active line:

# /etc/ax25/axports
#
# The format of this file is:
#
# name  callsign        speed   paclen  window  description
#
kiss    DL6RAI          9600    255     4       DB0AAB Link (438.300)
# end of /etc/ax25/axports

Now start kissattach to bind the TNC port to the kernel driver:

# /usr/sbin/kissattach /dev/tnc kiss

Note that ``kiss'' is the symbolic port name which is referred to in the /etc/ax25/axports file. You may give it any name.

kissattach should say something like: ``AX.25 port kiss bound to device ax0''. However, if you get the error message ``TIOCSETD: Invalid argument'', you forgot to add the Serial Port KISS driver for AX.25 to the kernel.

Now start listen and you should be able to monitor some traffic on the channel:

# /usr/bin/listen

Port kiss: AX25: DC1SLM->DB0AAB v DK1KMR* <RR R R3>

Port kiss: AX25: DB0AAB->DC1SLM v DK1KMR <I C S3 R6> pid=Text
0000  The quick brown fox

Port kiss: AX25: DB6MK-1->DG7DAH-1 v DB0AAB <RR C P R6>

Port kiss: AX25: DG7DAH-1->DB6MK-1 v DB0AAB* <RR R F R6>

Port kiss: AX25: DB6MK-1->DG7DAH-1 v DB0AAB <I C P S7 R6> pid=IP
IP: len 44 44.130.56.134->44.130.56.21 ihl 20 ttl 64 prot TCP
TCP: 1489->119 Seq xe86f491d SYN Wnd 31744 Data 4
0000  ....

Port kiss: AX25: DG7DAH-1->DB6MK-1 v DB0AAB* <REJ R F R6>
^C

Interrupt it with ctrl-C.

We can now try to make a connect with the call program. my TX delay parameter slightly to make the program work. At DB0AAB only very short TXDs are accepted, otherwise one will receive a message saying: ``TX Delay too long''. Adjusting the TX delay is done with the kissparms program.

# /usr/sbin/kissparms -p kiss -t 150

Then give it a try:

# /usr/bin/call -r kiss db0aab

GW4PTS AX.25 Connect v1.11
Trying...

You should see your PTT LED go on and off and after a while you should succeed to connect:

*** Connected to db0aab
Rawmode
PC/FlexNet V3.3e - Muenchen/Fachhochschule - PR56/RS36 - 9600Bd FSK
=>

Congratulations! You have now mastered step three of the CLX installation! After having disconnected, you may kill the kissattach program still running. We don't need it at this time.

2.5 Configuring TCP/IP

CLX needs TCP/IP to communicate. Theoretically, it would be possible to have several modules of CLX running on different machines as they are all using the same mechanism.

All what it needed now is that you can reach yourself by TCP/IP. This is probably working already. Try the following command:

# ping localhost

If you receive the following, everything is in order and you can continue with the next step. Use ctrl-C to abort ping.

PING localhost (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=1 ms
64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=1 ms
^C
--- localhost ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 1/1/1 ms

However, if you get the following answer, something is not yet set up correctly.

PING localhost (127.0.0.1): 56 data bytes
ping: sendto: Network is unreachable
ping: wrote localhost 64 chars, ret=-1
^C

In one of the rc files in /etc or /etc/rc.d (depends on your Linux installation) you must activate networking with the following commands:

ifconfig lo 127.0.0.1
route add localhost

See your Linux documentation for details. Having mastered this, you have now completed step four of the CLX installation.

2.6 Adding Shared Library Paths

With version 3.00 of the CLX software, we have introduced a shared library image in the ~/lib directory. For shared libraries to work in general, it is necessary to enable the dynamic linker ld.so to find these images at runtime.

Generally under Linux there are several ways to get around the problem:

  1. setting the $LD_LIBRARY_PATH environment variable
  2. make symbolic links to the default directories /lib or /usr/lib
  3. Add the paths to /etc/ld.so.conf
  4. Use statically linked programs

Option 3 is the recommended way because this gives flexibility and should not be a problem. As root, edit the file /etc/ld.so.conf

# vi /etc/ld.so.conf

and add the following line

/usr/local/clx/lib

to the bottom of the list. Then save the file and inform ld.so to update its cache:

# ldconfig -v

It should now list the new directorie. You have now completed step five of the CLX installation.

By the way, you should remember that running this command after every update of the libclxccl.so is mandatory to make the programs see the new library.

2.7 Configuring Postgres

The Postgres package should be installed on your system but it needs some configuration before it can be used for CLX.

With the current SuSE 6.2 distribution I had to install two packages, namely postgres and pg_ifa. The second package contained interface programs to Postgres like psql which is used in many CLX scripts. Be sure to check this.

The next step is to initialize the database (if it has not been initialized any time before). Become user postgres and run initdb.

# su - postgres
$ initdb
$ ^D
#

Now, as root, start up the postmaster process. This is done using a startup script which should have been installed along with the postgres package.

# /sbin/init.d/postgres start

Be sure that a program named postmaster has started up now.

# ps auxw | grep postmaster
root       661  0.0  0.6  1208   416  ?  S    10:18   0:00 grep postmaster
postgres   235  0.0  1.5  4148  1000  ?  S    08:34   0:00 /usr/lib/pgsql/bin/postmaster -i 

Here is an important detail: Check the options by which postmaster was started. The -o option allows passing options to the postgres program which is later called from within CLX. Here, the -F option states that fsync() is not called transaction. This parameter improves performance and makes your disks run more quiet but carries the risk of data loss in case of a power outage or system crash. You must decide if you want one or the other.

Also note that Postgres keeps its data in a directory pointed to by the $PGDATA environment variable. This directory should sit on a disk with a lot of space since this is the place where all the CLX data goes to.

Again, as user postgres, you must add user clx_us to the Postgres users. For this, become user postgres and use the program createuser to add a new user and allow it to create databases and new users. clx_us must have Postgres superuser privileges in order to perform some of the essential functions like importing/exporting tables from and to files.

# su - postgres
$ createuser
Enter name of user to add ---> clx_us
Enter user's postgres ID or RETURN to use unix user ID: 101 ->
Is user "clx_us" allowed to create databases (y/n) y
Is user "clx_us" allowed to add users? (y/n) y
createuser: clx_us was successfully added
$ 

2.8 Create CLX database and tables

Now we are ready to create CLX's database tables. Become user clx_us and run the clx_db script:

# su - clx_us
$ clx_db

This will bring up a number of messsages where you can see that tables are being created.

If you have any old data to reload (when you are coming from a previous installation of CLX), do so now using the bup_db script. If this is a new CLX installation you can skip the following step.

$ cd backup
$ cp ../../clx.old/backup/* .
$ bup_db -r

This restore process may take a while, depending on how many records are in your tables. If you have many users and lots of DX information, this will take even an hour or two. To monitor the process, check out the size of the database files in the directory $PGDATA/base/clx_db.

Create the index files on the database tables. This too might take quite a while:

$ clx_idx

Now we are done with everything and ready to start up CLX for the first time.

2.9 Starting CLX for the first time

We are now ready to start CLX for the first time. You might want to edit the default config file in ~/config/clx_par but if you've followed the instructions so far, you should not need to make any changes. Leave the callsign string as it is now, the callsign will be XX0XX.

Now as clx_us, start CLX with the following command:

$ clx -u

You should now see CLX coming up for the first time.

Reading /usr/local/clx/config/clx_par.
Decoding callsign.

*** CLX System Parameters ***

callsign:   xx0xx
database:   clx_db
interface:  AX25

Checking directories and file permissions
Clearing shared memories.
Clx coming up...

clx_ctl  Shared Memory manager           ....up
int_com  Internal Communications Manager .. up
snd_ctl  Transmit Spooler                .. up
usr_ctl  User Administration             .. up
iu_com   Inter-User communication        .. up
icl_com  Inter-Node communication        .. up
usr_req  User Database Interface         .. up
mb_ctl   Mailbox Controller              .. up
udt_mng  User Data Table Manager         .. up
usc_mng  User Commands Manager           .. up
usr_dlg  User Dialog manager             .. up
bbs_if   BBS interface                   .. up
rm_disp  Received messages Dispatcher    .. up
rcv_ctl  Received messages Spooler       .. up
con_ctl  AX.25 interface                 .. up

Clx is up.
$ 

When CLX is running, you will be returned to the $ prompt. You can now log into CLX with the term_usr program. CLX should greet you with a message and then display the clx > prompt.

$ term_usr
Hi om, Tere is XX0XX! a Linux-PacketCluster node running CLX...
xx0xx-16 de xx0xx    4-Dec-1999 1145Z   clx >

Now you can try a few commands, like SH/US, DX, SH/DX, SET/NAME etc. Logout with ``BYE''.

Shutdown CLX with the following commmand:

$ clx -s

Congratulations! You have successfully installed CLX on your system. If you are now willing to run CLX on the air, continue with section Configuration further down below!

2.10 Migrating from an older CLX installation

If you are migrating from an older CLX installation you will probably be interested in preserving some of the data you have acquired and some of the configuration work you have made up to that point. Here is a step-by-step description how you can save your previous work.

Basically the migration is easy as all user data is contained in either the database tables or the ~/box directory. Additionally, your configuration is stored in ~/config/clx_par and probably in ~/config/cluster_par. So these are the things to backup.

  1. Shutdown CLX and backup the user data
    $ cd
    $ clx -s
    $ bup_db -s
    
    The bup_db script will dump all database tables from a previous version and additionally store the mailbox messages in a .tgz file.
  2. Login as root and rename CLX's home directory to clx.old. We will need to read some files from there later. Now unpack the CLX distribution from the archive.
    # cd /usr/local
    # mv clx clx.old
    # cd /
    # tar xvzf clx_XXX.tgz
    
  3. If you want to replace the Postgres database system or if database structures within CLX have changed, you must perform the steps for initializing the CLX database as described in Configuring Postgres. You should consult the CLX release notes to decide if this step is necessary or not. When you are done, you should finish with the new postmaster process running and the CLX tables newly created, data read back in and index files created.
  4. Go to the ~/config directory and copy the old configuration files there. Edit the old one and add anything which you feel is necessary.
    $ cd ~/config
    $ mv clx_par clx_par.sample
    $ cp ../../clx.old/config/cluster_par .
    $ cp ../../clx.old/config/clx_par .
    $ diff clx_par clx_par.sample
    

Also, you might be interested to copy the old ~/.profile from the ~/../clx.old directory, but watch out for any changes before you overwrite the default ~/.profile.

This completes the migration steps. Easy, no?

2.11 Migrating from a Pavillion PacketCluster installation

The original Pavillion PacketCluster software and CLX have very little in common when it comes to programs. None of the original programs is working with CLX, database structures are quite different so generally installing CLX means starting from 0.

However, to make your and your users' lives a little easier we provide a migration tool for data.


Next Previous Contents