Install Multiple Palace Chat Servers on FreeBSD


Synopsis

If you want to host and run Palace Chat Servers for yourself and/or others then this documentation will outline the necessary steps on a preconfigured FreeBSD system.

This document will not explain how to install and configure FreeBSD. If you need assistance with that I'm happy to help.

For brevity I am using dynamically loaded kernel modules and FreeBSD's Package Management system.

[top]

Requirements

Root access is required for all the commands.

The Linux version of the Palace Chat server is used and as such FreeBSD will be required to run the Linux compatibility environment. This is available as a precompiled package. Internet access from your server is required.

You'll need a Serial Number for your Palace Server which can be obtained freely from The Palace Portal website.

Download the Palace Chat Server software from The Palace Legacy Project or from here.

[top]

Enable Linux Compatibility

Load Linux Kernel Modules

Before installing the Linux compatibility environment, two Linux kernel modules must be loaded:

kldload linux.ko
kldload linprocfs.ko

In order to make these kernel modules persistent across server reboots, they need to be added to the /boot/loader.conf file:

echo 'linux_load="yes"' >> /boot/loader.conf
echo 'linprocfs_load="yes"' >> /boot/loader.conf

Install and Enable the Linux Compatibility Environment

pkg install linux_base-c7
echo 'linux_enable="yes"' >> /etc/rc.conf.local
echo 'linproc /compat/linux/proc linprocfs rw 0 0' >> /etc/fstab
mount linproc

Reboot

To ensure your configuration is persistent, reboot now and check the kernel modules have loaded:

kldstat
ls /compat/linux/proc

[top]

Install Palace Chat Server Base

Note: Do not use Apache 1.2.6 which is distributed with the release as it is no longer supported and has known vulnerabilities. As such, do not run the install or setup scripts within the archive. Use a preconfigured webserver to host media files. This will be a manual install to ensure only the necessary files are copied and that they are copied to the standard locations within FreeBSD.

This process only needs to be done once.

Create User Group

Each Instance created will have its own user account and be associated with this group.

pw groupadd -g 9998 -n palace

Extract Palace Chat Server

tar -zxf pserver-4.5.1.i686-unknown-linux.tgz && cd pserver-4.5.1.i686-unknown-linux

Copy Base Binaries

Copy pserver and psfront to /usr/local/bin and set permissions:

cp arch/pserver arch/psfront /usr/local/bin
chgrp palace /usr/local/bin/pserver
chgrp palace /usr/local/bin/psfront

Create Base Root Directory

Create the root directory in FreeBSD's standard location for third party applications and set ownership and permissions:

mkdir /usr/local/palace
chown root:wheel /usr/local/palace
chmod 751 /usr/local/palace

Create Base Log Directory

Create the log directory in FreeBSD's standard location and set ownership and permissions:

mkdir /var/log/palace
chown root:wheel /var/log/palace
chmod 751 /var/log/palace

Create Base PID Directory

Create the PID directory in FreeBSD's standard location and set ownership and permissions:

mkdir /var/run/palace
chown root:palace /var/run/palace
chmod 770 /var/run/palace

Create Instance Skeleton Directory

This will be used as the skeleton structure for new instances.

mkdir /usr/local/palace/skeleton
cp -R instance/psdata /usr/local/palace/skeleton
cp -R instance/media /usr/local/palace/skeleton
chown -R root:wheel /usr/local/palace/skeleton
find /usr/local/palace/skeleton -type d -exec chmod 750 '{}' \;
find /usr/local/palace/skeleton -type f -exec chmod 640 '{}' \;

Cleanliness is next to Godliness...

rm /usr/local/palace/skeleton/psdata/.htaccess

[top]

Install Palace Chat Server Instance

This process should be done for each Palace Chat Server you want to run.

Create Instance User

Each instance should have its own user account to minimise disruption from unforeseen circumstances. The naming convention used is your choice.

The following command creates a disabled user account with no interactive shell, its primary group set and the home directory to the instances root directory.

pw useradd blackbox -c "Blackbox Palace User" -d /usr/local/palace/blackbox -g palace -s /usr/sbin/nologin

Create Instance Root Directory

mkdir /usr/local/palace/blackbox
chown blackbox:wheel /usr/local/palace/blackbox
chmod 750 /usr/local/palace/blackbox

Create Instance Log Directory

mkdir /var/log/palace/blackbox
chown blackbox:wheel /var/log/palace/blackbox
chmod 750 /var/log/palace/blackbox

Populate Instance from Skeleton

cp -R /usr/local/palace/skeleton/psdata /usr/local/palace/blackbox
chown -R blackbox:wheel /usr/local/palace/blackbox
cd /usr/local/palace/blackbox/psdata

Rename pserver.pat

Room configuration file. Don't edit the contents of this just rename the template file.

mv pserver.pat.tmpl pserver.pat

Edit pserver.conf

Configuration options for the pserver process.

mv pserver.conf.tmpl pserver.conf
vi pserver.conf

Modify the following variables.

SERIALNUMBER "%SERIALNUMBER%"
LOGFILE "/var/log/palace/blackbox/pserver.log"
SERVERROOT "/usr/local/palace/blackbox/"

Unless you have multiple IPs on your server, the port for this variable will need to be different for each instance.

FRONTEND "9998" "0.0.0.0"

Edit pserver.prefs

Configuration options for chat rooms.

mv pserver.prefs.tmpl pserver.prefs
vi pserver.prefs

Modify the following variables.

SERVERNAME "Blackbox"
SYSOP "Blackbox Owner"
URL "palace://blackbox.dynode.net:9998"
HTTP_URL "http://www.dynode.net:80/palace/blackbox/media/"
AVATAR_URL "http://www.dynode.net:80/palace/blackbox/avatars/"

Copy Media to Webserver

Copy the contents of /usr/local/palace/skeleton/media to palace/blackbox/media relative to the root directory of your webserver.

Jump to Add Instance to Run Control Configuration.

[top]

Install Run Control Script

The following script controls the start up and shut down of the Palace Server both interactively and systematically.

Save it as /usr/local/etc/rc.d/palace:

#!/bin/sh

# PROVIDE: palace
# REQUIRE: DAEMON
# KEYWORD: shutdown

. /etc/rc.subr

name="palace"
rcvar=palace_enable

command="/usr/local/bin/pserver"

start_cmd="${name}_start"
stop_cmd="${name}_stop"
status_cmd="${name}_status"

palace_start()
{
 local instance pidfile pid username

 echo "Starting Palace Servers:"

 for instance in ${palace_instances}; do
  pidfile="/var/run/palace/${instance}.pid"
  pid=$(check_pidfile ${pidfile} ${command})
  eval username="\${palace_${instance}_user}"

  /usr/bin/printf "%25s " "${instance}"

  if [ ! -d "/usr/local/palace/${instance}" ]; then
   echo "Unknown Instance"
   continue
  fi

  if [ -n "${pid}" ]; then
   echo "Already running? (pid=${pid})"
   continue;
  fi

  /usr/sbin/daemon -f -u ${username} -p ${pidfile} $command -f /usr/local/palace/${instance}/psdata/pserver.conf -s /usr/local/palace/${instance}/psdata/plugin.conf
  echo "Started"
 done
}

palace_stop()
{
 local instance pidfile pid pids

 echo "Stopping Palace Servers:"

 for instance in ${palace_instances}; do
  pidfile="/var/run/palace/${instance}.pid"
  pid=$(check_pidfile ${pidfile} ${command})

  /usr/bin/printf "%25s " "${instance}"

  if [ -n "${pid}" ]; then
   pids="${pids} ${pid}"
   kill ${pid}
  fi

 done

 if [ -n "${pids}" ]; then
  wait_for_pids $pids > /dev/null
  echo "Stopped"
 else
  echo "Not running"
 fi
}

palace_status()
{
 local instance pidfile pid

 /usr/bin/printf "%25s %s\n" "Instance" "Status"
 /usr/bin/printf "%25s %s\n" "-------------------------" "------------"

 for instance in ${palace_instances}; do
  pidfile="/var/run/palace/${instance}.pid"
  pid=$(check_pidfile ${pidfile} ${command})

  if [ ! -d "/usr/local/palace/${instance}" ]; then
   /usr/bin/printf "%20s %s\n" "${instance}" "Unknown Instance"
  elif [ -n "${pid}" ]; then
   /usr/bin/printf "%25s %s\n" "${instance}" "Running"
  else
   /usr/bin/printf "%25s %s\n" "${instance}" "Not running"
  fi
 done
}

load_rc_config $name

cmd_arg="$1" ; shift

if [ -n "$*" ]; then
 palace_instances="$*"
fi

run_rc_command "${cmd_arg}"
chmod 755 /usr/local/etc/rc.d/palace
echo 'palace_enable="YES"' >> /etc/rc.conf.local

[top]

Add Instance to Run Control Configuration

When adding a new instance the /etc/rc.conf.local file needs to be updated. One variable needs to be amended and another created.

The variable palace_instances is a space separated list of instances that are installed and palace_<instance>_user defines the user account the instance runs as.

palace_instances="blackbox"
palace_blackbox_user="blackbox"

If I were to install a new instance called newinst:

palace_instances="blackbox newinst"
palace_newinst_user="newinst"

Overall, the palace variables in the rc.conf.local file would look as such:

palace_instances="blackbox newinst"
palace_blackbox_user="blackbox"
palace_newinst_user="newinst"

[top]

Control Instances

Starting and stopping instances is done systematically. If you want to stop this behaviour then set the palace_enable variable in /etc/rc.conf.local as such:

palace_enable="NO"

Controlling instances interactively is done by running the service command which in turn executes the /usr/local/etc/rc.d/palace script.

Start and stop all instances:

service palace start
service palace stop

Start and stop one instance:

service palace start blackbox
service palace stop blackbox

In order to find out the status of the instances:

service palace status
service palace status blackbox

[top]

Copyright 2018