System Requirements
Kplex compiles and runs on Gnu/Linux MacOS X, FreeBSD and NetBSD. It should be possible to get it to compile on any POSIX-compliant system without too much effort. As kplex tries not to be hardware dependent and should run on 32 or 64 bit, big or little-endian systems.
kplex has been compiled on some router OSes such as OpenWRT and Tomato.
The primary development and testing platforms are GNU/Linux on x86-64 and ARMv6 (Raspberry Pi).
Obtaining kplex
kplex is currently being distributed as a source tar file which should compile on all supported platforms, or for selected platforms as a binary Debian package. The .debs are initially for the two primary development platforms: x86_64 (compiled on Ubuntu 12.04) and armhf (compiled on Raspbian "Wheezy" on a version 1 Pi model B but works happily on other Pis including the v2).
If enough requests are received for binaries in a specific format (e.g. rpm) these will be considered. MacOS dmgs will not be worked on until some sort of GUI has been constructed. All downloads can be found here.
Installing
From .deb
dpkg -i ./kplex_1.0-1_amd64.deb (substitute the name of the platform-specific package you downloaded as necessary)
There is no compiling required when installing from a binary package, so you're ready to skip to configuration.Installing 32 bit packages on 64-bit ARM OS
A 64-bit ARM package will be provided with a future release but doesn't currently exist.
Frederic Guilbault identified that the following is required to satisfy dependencies
for the 32-bit ARM package on 64-bit OSes prior to kplex installation:
apt-get install gcc-8-base:armhf libc6:armhf libgcc1:armhf
His installation procedure for kplex 1.4.1 is documented here:
https://github.com/lysmarine/lysmarine_gen/blob/master/lysmarine/31-kplex/run.sh
From Source
Unpacking
kplex source is distributed as a compressed tar file. Open a terminal window,
change directory to the place where you downloaded kplex and unpack the flie:
tar zxf <filename>
where <filename> is the kplex .tgz file you just
downloaded, e.g.:
$ tar zxf kplex-1.0.tgz
Now change into the diretory created:
$ ls
kplex-1.0 kplex-1.0.tgz
$ cd kplex-1.0
$
Compiling
kplex requires no special libraries in order to build or run other than what should already be installed on your system.
On MacOS X or GNU/Linux just type "make". On FreeBSD and operating systems where
"make" is not GNU make use "gmake" wherever "make" appears in these instructions
(gmake is not part of the FreeBSD base system and may need installing).
$ make
cc -Wall -c -o kplex.o kplex.c
cc -Wall -c -o fileio.o fileio.c
cc -Wall -c -o serial.o serial.c
cc -Wall -c -o bcast.o bcast.c
cc -Wall -c -o tcp.o tcp.c
cc -Wall -c -o options.o options.c
cc -Wall -c -o error.o error.c
cc -Wall -c -o lookup.o lookup.c
cc -Wall -o kplex kplex.o fileio.o serial.o bcast.o tcp.o options.o error.o lookup.o -pthread -lutil
There should be no errors or warnings reported during compilation. If there are,
please let me know details of your system and compiler.
Installing
"make install" will install the kplex binary and should be done with root
privileges. The default installation location is /usr/bin on Linux systems,
/usr/local/bin on other systems. These can be modified using the BINDIR
variable. For example, to install kplex in /usr/sw/bin:
sudo make -DBINDIR=/usr/sw/bin install
Invocation at boot time
For portable computers It is not usually required to have kplex start automatically on system boot, but for servers such as a headless raspberry pi it is often desirable. The standard mechanism for starting daemon processes on most *nix-like systems when kplex was first written was using init scripts. More recent Linux distributions (including versions of raspbian based on 2015's Debian "Jessie" onwards) have replaced init with systemd but retained legacy support for startup via init scripts. Some users have reported problems with systemd attempting to start kplex before all network interfaces are fully initialised. Consequently, those wishing to use kplex with systemd-based systems which use kplex over dynamically configured network interfaces (and almost all raspberry pi users unsure what to do here) should skip to the systemd section below.
Invocation at boot time via init scripts
A sample debian/ubuntu init script is provided with the source distribution (as kplex.init). An example init script for RedHat/CentOS systems is here. If kplex is run from init scripts, you are strongly advised not to run it as root and ideally to run in a chroot-ed/jailed environment.
If you install kplex from .deb an init script /etc/init.d/kplex is installed as part of the package. You can make kplex start at boot time by issuing the following command which adds appropriate start/stop links::
sudo update-rc.d kplex defaults
The above change can be backed out at a later point as follows:
sudo update-rc.d -f kplex remove
A future enhancement to this page will be documenting adding kplex startup to launchd (OS X), systemd (newer linuxen) etc.
Invocation at boot time via systemd unit file
If you installed kplex from a .deb, remove the installed init script:
sudo mv /etc/init.d/kplex /usr/share/kplex/kplex.init
Do not attempt to use the unit file distributed with kplex 1.4 or earlier. Instead download a new one:
sudo wget -O /lib/systemd/system/kplex.service http://stripydog.com/download/kplex.service
Enable the kplex service:
sudo systemctl enable kplex
To start kplex without waiting for a system reboot:
sudo systemctl start kplex
Configuring and Running kplex
Full instructions on how to configure and run kplex are given in the README file in the kplex source distribution which is also availble online here. There is a lot of detail in there so users with basic requirements may prefer to start with the quickstart instructions
Providing Feedback
Contact details for feedback including bug reports and suggestions are contained in the README file. If kplex works for you or if it doesn't, do please let me know! If you're having trouble downloading the source you can try using the contact form here.
