Managing configurations for Director Toolkit on Unix/Linux

To control/view the Director on a Unix/Linux box, you need to set up tunnels and connect in with Putty before you start up the Director on the Windows box. Follow the steps below to connect to Director Toolkit running on a remote Unix/Linux instance. On the remote Unix/Linux instance, add/modify the JmxPort setting in DirectorSettings.xml. This value represents the port that you want to connect to.

<Setting Value="8996" Name="JmxPort" />

Add the following to eFORMz startup parameters. This needs to be added to all eFORMz startup scripts. Check /minisoft/eformz_start.sh and the service file: /lib/systemd/system/eFORMzServiceManager.service

-Djava.rmi.server.hostname=localhost

Stop and restart eFORMz on the Linux instance. Verify that the JmxPort is active on the Linux instance:

netstat -aon | grep 996

You should see something like this:

[eformz@eformz-demo minisoft]$ netstat -aon | grep 96 
tcp        0      0 0.0.0.0:8996            0.0.0.0:*               LISTEN      off (0.00/0/0)
tcp        0      0 0.0.0.0:9996            0.0.0.0:*               LISTEN      off (0.00/0/0)

8996 – this is the JmxPort specified in DirectorSettings.xml

9996 – this is the standard port used by Director

On Windows, verify that port 9996 is not already in use. If you have eFORMz Service Manager or Director running locally on your Windows box, you will not be able to use 9996 as a tunnel. Shut down or stop local eFORMz Service Manager or Director. Execute the following in a command prompt:

netstat -aon | findstr "996" 

This will verify that ports 8996 and 9996 are unbound.

On Windows, start Putty and load the session that you normally use to SSH into the remote Unix/Linux instance. Expand the SSH node and click on “Tunnels”. Create the following Tunnel configurations:

Set Source port to the JmxPort value (8996). Set Destination to be localhost:8996. Do the same for Director’s default port: 9996

Save the SSH configuration and then click open. Verify that your local tunnels are active by running:

netstat -aon | findstr "996"

At this point, you can interact with the remote Linux instance’s Director Toolkit, but how you interact with it will depend on what you need to do. If you need to access the Director tab to Start and Stop Director configuration files, do the following:

1. On Windows, start eFORMz and select Host Tools | Local Director Toolkit. This will bring up Director Toolkit, but since your tunnels (8996 and 9996) are active you are actually interacting with the Director Toolkit running on the remote Linux instance.
2. Switch to the Director tab. If the remote Linux instance has active Director configurations you should see them up and running along with any associated logging. This is similar to viewing local Director configurations, except in this case you are looking at the remote Director. You can start/stop the remote configurations from this Director Toolkit instance.

If you need to change a remote configuration or change Printers, Databases, Archives, PrintServices, you need a separate Director Toolkit instance.

1. In eFORMz, go to Host Tools | Unix | Director Toolkit. You should see a new Director Toolkit dialog appear. It might take a few seconds to render as it connects to the remote Director.
2. In this Director Toolkit instance, you will be able to change Director configurations, add/remote printers, modify database connections/archives/print services.

When you are done, make sure you exit/disconnect your Director Toolkit connections before exiting out of your SSH session.

Using command line controls to interact with the Director from an SSH session

java -jar Run.jar – com.minisoft.Director.manage.DirectorCommand [options]

where [options] are:

host= – default is “localhost”
port= – default is 9996
user= – Director management user name
password= – Director management password
shutdown – Shut down the Director
status – Display the running configurations
startcfg= – Start the named configuration file
stopcfg= – Stop the named configuration
restartcfg= – Restart the named configuration
reload=eformzcfg – Reload the eFORMzCfg.xml files
reload=printerscfg – Reload Printers.xml
reload=databasescfg – Reload Databases.xml
reload=archivecfg – Reload Archives.xml

com.minisoft.Run.ServiceController 9995
com.minisoft.Director.Director 9996
com.minisoft.mta.service.Service 9997
com.minisoft.webserver.WebServer 9998

If the web page is used, the default ports are 8000 and 8001. The web server is configurable and may use alternate ports. The SSH port is one eFORMz uses. The service (sshd) is provided by the operating system and may use an alternate port.

The four ports used by the eFORMz controllers are fixed and cannot be configured to use an alternate for listening. That said, if the server with eFORMz is being a “NAT” firewall, the firewall can translate between two port numbers. The private address for Director must be 9996. With NAT, the public address can be any other available port number.

While not required, it may be convenient to use the Server Manager to launch and control Director for cloud customers who have limited access to the system.

java -jar Run.jar - com.minisoft.Director.manage.DirectorCommand user=minisoft password=password restartcfg=LocalPM.cfg

eFORMz as a service on Linux/UNIX

If a situation arises where a termination of the background process is needed, please take note of the following.

• The normal signal to send should be 1, 2, or 15.  These are equivalent to eFORMz. Processing will shutdown in an orderly fashion. This may take some time as files currently being processed will complete.
• If an immediate stop of eFORMz is required, use 9.  This will stop processing without waiting for completion. Partial spool files may print. In use files will not have disposition handling and will start over when processing resumes.
• Use of 4, 5, 6, 7, 8, 10, 11, 12, 13, and 14 are not recommended and will result in unexpected behavior.
• Using a signal value of 3 (SIGQUIT) will not stop eFORMz. This signal will attempt to write extra trace information (stack trace ) to the stdout.

NOTE: When using systemd to manage the eFORMz service, the default shutdown is via signal 15 (SIGTERM). This may not stop processing immediately if a large or otherwise time consuming process is active. A restart using systemd can fail if a script to wait for eFORMz to complete is not configured.

Sample:

root@lithium:/minisoft# ps -ef | grep java
root 14201 1 99 14:35 ? 00:00:04 java -mx1024m -ms128m -jar Run.jar -Monitor=true -
root@lithium:/minisoft# kill -15 14201
root@lithium:/minisoft# ps -ef | grep java
root@lithium:/minisoft#

Linux/UNIX Signal number to name table:

1) SIGHUP
2) SIGINT
3) SIGQUIT
4) SIGILL
5) SIGTRAP
6) SIGABRT
7) SIGBUS
8) SIGFPE
9) SIGKILL
10) SIGUSR1
11) SIGSEGV
12) SIGUSR2
13) SIGPIPE
14) SIGALRM
15) SIGTERM