Configuration issues when upgrading to version 6

When I upgraded a test server to version 6, it would no longer start successfully. I received a series of errors about my configuration file. Whilst I can manually fix these on my test server, what do I do about my customers and their existing configuration files? It will be a major pain to provide them all with instructions on what they have to manually add or remove from the LS config file just to be able to run with the new version. Is there anything I can refer to that documents this sort of thing? Do I just comment out the obsolete stuff or am I supposed to replace it?

These are the errors I got in the order I received them:

Error	Solution
"Unexpected obsolete <monitor_enabled> element"	commented it out
"Unexpected obsolete <monitor_provider> element"	commented it out
"Mandatory configuration tag 'mpn.reaction_on_database_failure"	added it in
No monitoring page anymore	added <dashboard> element

:confused:

I guess what I am saying here is that I should be able to install the new version and not have to then give out instructions to customers on how to manually change their bespoke config files to work with the new version. It should be backward compatible. If <monitor> is replaced with <dashboard> it shouldn't just fail to start. At worst it should be a warning. Also why is MPN mandatory when it wasn't before? Presumably a new demo that gets included by default requires it? If so, can I get around it?

Ideally, at the very least, I would like to get a migration tool that would parse and correct an old config file so that it will work with version 6 without manual intervention........please :)

Hi Kevin,

I am very sorry for all the troubles you encountered in trying to migrate to Lightstreamer version 6.0.
Indeed, the changes, compared to the version 5, are so many and configuration files have changed substantially also.

Our suggestion to approach the upgrade is to start from the factory files of LS 6 and manually re-apply all the customizations (usually on configuration files and Adapter deployment, but also the start script and other files in the conf directory may be involved). Please refer to the "HOW TO UPGRADE" section of README file.

We acknowledge that this may be a very annoying task, which involves diff operations between your production files and the factory version of version 5; and once marked variations re-apply these in the new LS 6 files.
I confirm you that we are seriously thinking of making some tool available.

Regards,
Giuseppe

I am afraid for me it represents too much of a risk to upgrade to version 6. If it were simply my own installation then it not a problem, but for those of us who redistribute LS with our own software to a customer base, it is not practical to go through such a manual exercise unless there is a very good reason for the customer to update to version 6. At the moment, for our stuff, the only motivation is to "keep up to date" because there is no new functionality (or bug fixes) that are "must haves" yet. If we send a new release with a load of instructions regarding manual changes to LS config - which we cannot test beforehand - they are going to be asking why. If they get errors as a result of a misconfiguration then that will be worse still.

The only circumstances in which I could do this would be if I could run a script to migrate their existing configurations without risk. Obviously this is something I could write and test, but I am not sure I have the time yet.

Kevin,

Do you think that an online tool to which you can submit config files and get back the upgraded version would be good enough?

You would still have to re-deploy your adapters manually, but the config files conversion would be automatic.

Thanks
Alessandro

I don't seem to have had any need to do anything with my adaptors. They seem OK. Is that not expected?

An online tool may be useful in the long term - but in the meantime I have managed to create a little tool that does it for me that I am now testing.

I meant that to upgrade to LS6, you have to do a fresh install, then copy your adapters and upgrade the config files. The config file upgrade would be managed through an automated tool, but you would still have to copy your adapters by hand. In other words, that's not going to be a full automated installer/upgrader, but a helper in converting config files.

Good to know you were able to create your own conversion tool!

OK - yes that sounds good. My little tool just reads through the old config file and applies customisations to a fresh version.

One thing the doco mentions is potential changes to the startup scripts also. I wonder if I need to consider that - because I have to write my own IBMi startup script (based on the supplied unix-like scripts). Is there anything significant for me to be worried about? It all seems to start and stop OK.

The launch script LS.sh has changed significantly with LS 6, for several reasons:

1. the introduction of different ClassLoaders to separate the code into various parts;
2. the introduction of new third-party libraries;
3. the spreading of the third-party libraries in separate directories.

If you have replaced only the other scripts, no problem, but If you have changed LS.sh it should not work because of 2 and 3.
Do you mean that you have manually modified the classpath to account for 2 and 3?
In this case it might work, but you would lose the benefits of the ClassLoader separation, with the risk of class conflicts.

In general, we expect that someone could change the launch script to add JVM command line arguments or similar customizations; in this case, the same customizations can be easily replicated to the new script.
If your case is more complex, we can help you with this merging.

Here is my IBMi LS.sh

Code:

---

#!/bin/sh


# =======================================================================
# === CHECK THIS OUT
# =======================================================================
# JAVA_HOME must point to your Java Development Kit installation
JAVA_HOME="/QOpenSys/QIBM/ProdData/JavaVM/jdk70/64bit"


# =======================================================================
# === CHECK THIS OUT
# =======================================================================
# JAVA_OPTS should contain any Java Virtual Machine options. Here are some tips:
# 1) Give more RAM to the server process, especially with heavy traffic, by specifying a min and max "heap"
#    E.g.: If you have 4 GB and the box is dedicated to Lightstreamer, you might set 1 GB min heap and 3 GB max
#    heap with these options: "-Xms1G -Xmx3G"
# 2) Choose a better "garbage collector" if you want to reduce latency. An option that often gives good results is:
#    "-XX:+UseConcMarkSweepGC". If you are using Java 7 (apart from early versions) or later, you might prefer to try:
#    "-XX:+UseG1GC". Many other tuning options are available (please see Oracle docs).
# 3) Configure the garbage collector in such a way as to prevent long pauses. Choose the maximum pause based
#    on your latency and throughput requirements, but consider anyway that GC pauses cause the  connection
#    to stay idle and pauses longer than 4 or 5 seconds may cause the clients to timeout and reconnect.
# 4) On some IBM servers we need to use the -Xint to switch off the JIT compiler. Later OS releases may have fixed this.


JAVA_OPTS="-XX:+UseConcMarkSweepGC -XX:+HeapDumpOnOutOfMemoryError -XX:MaxGCPauseMillis=1000"


echo "Java environment:"
echo "JAVA_HOME = \"${JAVA_HOME}\""
echo "JAVA_OPTS = \"${JAVA_OPTS}\""
echo


# =======================================================================
# === CHECK THIS OUT
# =======================================================================
# In order to serve many concurrent user connections,
# the limits on the available file descriptors should be released;
# these limits also apply to the open sockets


FD_HARD_LIMIT=`ulimit -Hn`


# if running as root, you may be able to increase the hard limit:
#
# ulimit -Hn unlimited
# FD_HARD_SET=$?
# FD_HARD_LIMIT=`ulimit -Hn`
# if [ $FD_HARD_SET -ne 0 ]; then
#    echo "Warning: could not enlarge maximum file descriptor limit"
#    echo "ensure that the current limit is suitable: " $FD_HARD_LIMIT
# fi


echo Setting file descriptor limit to $FD_HARD_LIMIT


ulimit -Sn $FD_HARD_LIMIT
FD_SOFT_SET=$?
FD_SOFT_LIMIT=`ulimit -Sn`
if [ $FD_SOFT_SET -ne 0 ]; then
    echo "Warning: could not enlarge current file descriptor limit"
    echo "ensure that the current limit is suitable: " $FD_SOFT_LIMIT
fi


# Dump current ulimit and sysctl values
echo "Configured file descriptors, soft limit: $(ulimit -Sn)"
echo "Configured file descriptors, hard limit: $(ulimit -Hn)"
fs_file=$(/sbin/sysctl -a 2> /dev/null | grep ^fs.file)
if [ -n "${fs_file}" ]; then
    echo "Configured sysctl fs.file.* values:"
    echo "${fs_file}"
fi
echo


# ---------------------------------------------------------------------------


# up two dirs there is LS_HOME
_LS_HOME=$(dirname "${0}")
if [ "${_LS_HOME}" = "." ]; then
    # in the same dir
    _LS_HOME=$(dirname "${PWD}")
elif [ -z "$(echo ${_LS_HOME} | grep "^/" 2> /dev/null)" ]; then
    # relative dir to target
    _LS_HOME="${PWD}"
else
    # absolute path
    _LS_HOME=$(dirname "${_LS_HOME}")
fi
LS_HOME=$(dirname "${_LS_HOME}")


echo "Lightstreamer Server directory:"
echo "LS_HOME = \"${LS_HOME}\""
echo


# Inherited from environment, write current PID to
# given file path (declared as WRITE_PID).
# This is useful for init scripts unable to figure
# out the pid by themselves (OpenBSD) and only
# works when Lightstreamer starts.
WRITE_PID="${WRITE_PID:-}"


# Variables for library paths
KERNEL_LIB_PATH=""
INTERNAL_LIB_PATH=""
LOGGING_LIB_PATH=""
DATABASE_LIB_PATH=""


if [ "$1" = "run" -o "$1" = "background" ] ; then


  echo Starting Lightstreamer Server...
  echo Please check logs for detailed information.
  class=com.lightstreamer.LS


  # Classpath
  cpath="$LS_HOME/lib/ls-bootstrap.jar:$LS_HOME/lib/ls-adapter-interface.jar"
  # move ls-adapter-interface.jar in the com.lightstreamer.logging_lib_path property below to have slf4j/logback visible by the Adapters


  KERNEL_LIB_PATH="-Dcom.lightstreamer.kernel_lib_path=$LS_HOME/lib/lightstreamer.jar"
  INTERNAL_LIB_PATH="-Dcom.lightstreamer.internal_lib_path=$LS_HOME/lib/ls-monitor.jar:$LS_HOME/lib/core/*:$LS_HOME/lib/mpn/*:$LS_HOME/lib/mpn/apns/*:$LS_HOME/lib/mpn/gcm/*"
  LOGGING_LIB_PATH="-Dcom.lightstreamer.logging_lib_path=$LS_HOME/lib/ls-logging-utilities.jar:$LS_HOME/lib/log/*"
  DATABASE_LIB_PATH="-Dcom.lightstreamer.database_lib_path=$LS_HOME/lib/mpn/hibernate/*:$LS_HOME/lib/lightstreamer.jar"


elif [ "$1" = "stop" -o "$1" = "restart" ] ; then


  echo Stopping Lightstreamer Server...
  class=com.lightstreamer.LS_Stop
  JAVA_OPTS=""


  # Classpath
  cpath="$LS_HOME/lib/ls-bootstrap.jar:$LS_HOME/lib/lightstreamer.jar"


else


  echo "Usage:  LS.sh ( command )"
  echo "commands:"
  echo "  run              Start Lightstreamer Server in foreground"
  echo "  background        Start Lightstreamer Server in background"
  echo "  stop              Stop Lightstreamer Server"
  echo "  restart          Stop Lightstreamer Server and start a new instance in background"
  exit 1


fi




# Configuration file
arg1=$LS_HOME/conf/lightstreamer_conf.xml


write_pid() {
  if [ -n "${WRITE_PID}" ]; then
      echo $$ > "${WRITE_PID}"
  fi
}


if [ "$1" = "restart" ] ; then


  # call command and wait
  eval '"$JAVA_HOME/bin/java" -cp "$cpath" $class "$arg1"'
  # now start a new Server
  write_pid
  exec $0 background


elif [ "$1" = "run" ] ; then


  # leave control to command
  write_pid
  exec "$JAVA_HOME/bin/java" $JAVA_OPTS "$KERNEL_LIB_PATH" "$INTERNAL_LIB_PATH" "$LOGGING_LIB_PATH" "$DATABASE_LIB_PATH" -cp "$cpath" $class "$arg1"


elif [ "$1" = "stop" ] ; then


  # leave control to command
  exec "$JAVA_HOME/bin/java" -cp "$cpath" $class "$arg1"


elif [ "$1" = "background" ] ; then


  # call command in a separate window and leave
  touch "$LS_HOME/logs/LS.out"
  write_pid
  exec "$JAVA_HOME/bin/java" $JAVA_OPTS "$KERNEL_LIB_PATH" "$INTERNAL_LIB_PATH" "$LOGGING_LIB_PATH" "$DATABASE_LIB_PATH" -cp "$cpath" $class "$arg1" >> "$LS_HOME/logs/LS.out" 2>&1 &


fi

---

I thought that you had had to change the syntax of the instructions and you were worried about porting those changes in the 6.0 script.
Now I see that you have already ported your custom preferences to the new 6.0 script and they are the normal customizations we expect, except that you have changed the initial comments too.
So, it seems that there is no problem at all.

OK good thanks. FWIW "-server" does not seem to be a valid option on the IBMi but I haven't investigated why.

Thank you for the tip. We will try to find a more resilient formulation.