Operations Cookbook

The Jive SBS platform is capable of encrypting HTTP requests via SSL or TLS. Enabling encryption of HTTP traffic requires the following steps on a platform-managed host:

• Copy cryptographic materials to the host. By default, the Jive HTTPD server attempts to load an X.509 certificate file from the path “/etc/jive/httpd/ssl/jive.crt” and the corresponding key from “/etc/jive/httpd/ssl/jive.key”. The paths to these files are configured in the default Apache HTTPD virtual host file located at “/etc/jive/httpd/sites/default.conf” and can be changed to any path desired.
• Enable SSL in the HTTPD server by specifying the “-D SSL” option in the Apache HTTPD configuration extension file located at “/etc/jive/conf/jive-httpd”. To enable SSL, open (or create) this file and add ‘OPTIONS=”-D”’ to the file.
• With either Jive SBS's HTTP server or behind a third-party load balancer, add two attributes to the file at /usr/local/jive/applications/<app_name>/conf/server.xml. To the first (HTTP) /Server/Connector element, add this: scheme="https" proxyPort="443".
• After making the changes above, restart the Jive HTTPD server as described in the run book for Linux or Solaris.

Many deployments will not wish to use the locally managed platform database instead, choosing to use an RDBMS that is controlled by an internal corporate IT group. In this case, the Jive SBS local database should be disabled. To disable the database, as the root user, execute the following script:

The following terminal output demonstrates deactivation and of the Jive database service:

On Linux

[root@biodome ~]# /etc/init.d/jive-database deactivate
Jive Database deactivated.
[root@biodome ~]# /etc/init.d/jive-database activate
Jive Database activated. The database will start automatically on the next system restart.

On Solaris

bash-3.00# svcadm -v disable -s application/jive/database
svc:/application/jive/database:default disabled.

In some circumstances, it may be desirable to change the default configuration of platform-managed application server instances. For example, on a larger server-class machine, an application instance will benefit from allocation of more RAM for the JVM heap.

To change this or other settings, edit the “instance” file for the desired application ("sbs" by default) located at /usr/local/jive/applications/<app_name>/bin/instance.

The contents of this file will vary from release to release. Generally, the entries in this file correspond to either:

• Environment variable values in the “setenv” script located in the same directory
• Tokenized configuration attributes for the “conf/server/xml” file in the application directory

As an example, to change the port that the managed application listens for AJP connections, edit the instance file to alter the port for AJP_PORT.

Prior to edit, the instance file will look similar to the following.

[0806][jive@melina:~/applications/sbs/bin]$ cat instance 
export JIVE_HOME="/usr/local/jive"
export AJP_PORT="9002"
export APP_CLUSTER_ADDR="224.224.224.224"
export JIVE_APP_CACHE_TTL="10000"
export APP_CLUSTER_PORT="9003"
export HTTPD_ADDR="0.0.0.0"
export AJP_BUFFER_SIZE="4096"
export HTTP_ADDR="127.0.0.1"
export JIVE_APP_CACHE_SIZE="10240"
export SERVER_PORT="9000"
export JIVE_NAME="sbs"
export HTTP_PORT="9001"
export AJP_ADDR="127.0.0.1"
export JIVE_CONTEXT=""
export AJP_THREADS_MAX="50"

To alter the AJP_PORT to listen on port 11000, edit the instance file to appear similar to the following.

[0806][jive@melina:~/applications/sbs/bin]$ cat instance 
export JIVE_HOME="/usr/local/jive"
export AJP_PORT="11000"
export APP_CLUSTER_ADDR="224.224.224.224"
export JIVE_APP_CACHE_TTL="10000"
export APP_CLUSTER_PORT="9003"
export HTTPD_ADDR="0.0.0.0"
export AJP_BUFFER_SIZE="4096"
export HTTP_ADDR="127.0.0.1"
export JIVE_APP_CACHE_SIZE="10240"
export SERVER_PORT="9000"
export JIVE_NAME="sbs"
export HTTP_PORT="9001"
export AJP_ADDR="127.0.0.1"
export JIVE_CONTEXT=""
export AJP_THREADS_MAX="50"

Many values contained in the application setenv script can be overridden in the instance configuration. Commonly modified values include:

• JVM_HEAP_MAX – the maximum JVM heap size in megabytes
• JVM_HEAP_MIN – the minimum JVM heap size in megabytes (should usually be set to the same as the JVM_HEAP_MAX value)

For any managed application, all files except the binaries for the web application (by default, each application is linked to these binaries located at /usr/local/jive/applications/template/application) are not managed by the application platform. As a result, any changes to files such as instance will be durable across application upgrades.

Jive SBS-managed databases will perform automatic backups as described in Auto Backups. In some situations, for example prior to an upgrade of the package, it may be desirable to perform a full database backup manually.

To manually perform a full backup of the managed database, execute the dbbackup script as the jive user.

[0801][jive@melina:~]$ ./bin/dbbackup
/bin/tar: Removing leading '/' from member names

The command will not produce any further output if successful and will return zero if successful, non-zero otherwise.

You can restore from a backup by using PostgreSQL commands. In the PostgreSQL documentation, the section on recovering from your backup is probably the most specific. For a broader view, be sure to see the contents of their documentation on backing up and restoring.

In order to integrate the Jive SBS platform with external load balancers, configure the load balancer for session affinity between each host running the application. If the load balancer is performing SSL session termination (recommended), the load balancer should be configured to route traffic to port 80 each package-managed server. If the load balancer is not performing SSL session termination, the load balancer should be configured to route traffic to port 443 and each server configured for SSL as described in the above cookbook recipe.

Depending on the load balancer, it may be necessary to add JVM route information to the outgoing JSESSIONID HTTP cookies sent to remote agents. In this case, add a jvmRoute attribute to the Engine element of the server.xml file located in the application’s conf directory (/usr/local/jive/applications/sbs/conf/server.xml by default). For example, to name the route “r1”, the server.xml Engine element would read:

<Engine defaultHost="localhost" name="Catalina" jvmRoute="r1">

When configuring multiple nodes with jvmRoute attributes, each node should have a different value.

Applications managed by the Jive SBS package manager are capable of accepting remote Java debuggers. To enable debugging, export environment variables “DEBUG” and “JPDA_TRANSPORT” prior to starting the managed application to be debugged.

For example, to debug via remote socket connection, start the desired application as shown below.

[0832][jive@melina:~]$ export DEBUG=1 && export JPDA_TRANSPORT=dt_socket && appstart sbs

Note that only one managed application may be debugged at a time. When running in DEBUG mode, the application JVM will halt until a debugger is attached.

You might find it easier to isolate cluster-related issues by creating a cluster of instances on a single machine. The following steps describe how you can create a simply two-node cluster on a single machine. This assumes you have a license that supports more that one node in a cluster.

1. Install the platform using the package manager and default settings.
2. Use the apprm command to remove the application you've installed, which installed it into the root ("/") context.

   apprm sbs

3. Use the appadd command to add two new application instances that will make up your cluster.
   1. You can add the first instance with default settings, specifying a context path:

      appadd --context-path=/cluster1 cluster1

   2. Add the second instance with the following suggested settings:

      [joe@targetmachine]$ appadd --ajp-port=9004 --server-port=9005 --http-port=9006 --cluster-port=9007 --context-path=/cluster2 cluster2

4. Restart the jive-httpd service (Linux, Solaris).
5. Start the first instance with the appstart command.

   appstart cluster1

6. With a browser, navigate to the setup tool (usually at http://<hostname>/cluster1, where hostname is the DNS resolvable name of the server where the package was installed) to configure the instance.
   Note: Be sure to use a license that supports more than one node in a cluster.
7. Stop the first instance with the appstop command.

   appstop cluster1

8. Change the APP_CLUSTER_PORT in the /usr/local/jive/applications/cluster2/bin/instance file to be the same as cluster1's cluster port. For more on making this change, see Changing the Configuration of an Existing Instance.
   Note: In version 3.0.0, to support clustering you'll need to change configuration to override a default setting. Edit the instance file for the instance to add the following (where <addr> is a unique address -- 224.224.224.224 might work.):

   export CUSTOM_OPTS="-Dtangosol.coherence.clusteraddress=<addr>"

9. Start the second instance.

   appstart cluster2

10. Use the setup tool to configure the instance (http://<hostname>/cluster2). When configuring the database, choose "external database," then use settings for the database from cluster1.
11. Stop the second instance.

    appstop cluster2

12. Start both instances.

    appstart

13. Use the admin console to turn on clustering on both instances. You'll find that setting at System > Settings > Caches.