Skip to main content

Start and stop the FairCom server

This section discusses multiple ways to start and stop the FairCom server.

Start

To start the FairCom server on any platform:

  1. Navigate to FairCom the folder.

  2. Run the product executable: faircom.exe (or faircom on Unix/Linux)

Linux

Start the FairCom server on Linux, Raspbian, and Unix

The FairCom server operates as a typical program on all supported Unix/Linux platforms. In these environments, FairCom recommends Administrators run the FairCom server in the background to decrease the chance of unwittingly terminating it — for example, # faircom &.

The no-hang-up option may also be used to keep the FairCom server from being terminated if the user starting the FairCom server logs off the system — for example, # nohup faircom &.

Script to start and stop the server

On Unix/Linux systems, a script can be used to start and stop the FairCom server. The script can be used to integrate the FairCom server as a startup service in systems where SystemD is used to manage the startup service. Some of the most recent Linux distributions using SystemD include RedHat 7, CentOS 7, Fedora, and Raspbian.

If the script is placed in the correct directory (such as /lib/systemd/system on CentOS 7), the systemctl system tool can be used to manage FairCom as a system service — for example, to enable the ctree.service at startup, use the systemctl enable ctree.service command.

Because the Unix/Linux packages are distributed as .tar.gz archives, where the files will be extracted cannot be controlled. Therefore, Example 1, “Script to start and stop the server” may need to be edited to match the paths used on your system.

In Example 1, “Script to start and stop the server”, uncomment 

A User= keyword may be used to start the service as a specified user:

The systemd tool must launch the service as root.

  1. In Example 1, “Script to start and stop the server”, uncomment #User=myuser line and

  2. Change myuser to the desired user name to start the service as a different user.

Note

  • The ctstop -auto command works ONLY if the default credentials are set. If you have changed these credentials, you would need to use the ctstop syntax to include the user ID and password in the script.

  • Including a password in the script is against security policy in most production environments.

Example 1. Script to start and stop the server

This sample script, called ctree.service, is an example of how to implement such a script.

[Unit]

Description=ctree database

After=multi-user.target network.target

[Service]

#Uncomment the next line if you want to start the service as a different use than "root"

#User=myuser

Environment=LD_LIBRARY_PATH=/opt/FairCom/linux.v2.6.x86.32bit/bin/ace/sql

WorkingDirectory=/opt/FairCom/linux.v2.6.x86.32bit/bin/ace/sql

ExecStart=/opt/FairCom/linux.v2.6.x86.32bit/bin/ace/sql/ctreesql

ExecStop=/opt/FairCom/linux.v2.6.x86.32bit/tools/cmdline/admin/client/ctstop -auto

Restart=on-abort

[Install]

WantedBy=multi-user.target


Windows

Manually start the FairCom server on Windows

If the FairCom server is not configured to run as a Windows service, there are multiple ways to start and stop it and to detect if it is currently running.

  1. The FairCom server opens and runs the Control Window, observe the name of your FairCom server at the top of this window.

  2. To start the FairCom server, double-click on the server executable in Windows Explorer: <faircom>\server\faircom.exe.

    Note

    When the FairCom server is running manually (not as a service), an icon is displayed in the Windows taskbar. Double-clicking this icon RunningIcon.png brings up the FairCom console window.

    c-treeConsole.png

  3. The FairCom console window provides troubleshooting information about the FairCom server.

    Note

    When connecting via a network, be aware that the local firewall may block the TCP/IP port used to communicate with the FairCom server. If you cannot connect to a running instance of the FairCom server, a firewall could be blocking communication. If so, you may need to unblock the FairCom server port, which defaults to 6597. For more details, see FairCom ports.

This window provides these menu options to shut down the FairCom server:

If you close this window, the FairCom server continues to run and the window is minimized to the taskbar.

  1. Open the Message Monitor window.

  2. Open the Function Monitor window.

Message Monitor window

The message window shows console messages.

The startup messages tell you information such as TCP/IP ports for applications to communicate with the FairCom server, license information such as the maximum allowed connections, and notice if the server is in DEMO mode, which shuts down automatically every three hours.

Figure 1. Message Monitor
Message Monitor


Function Monitor window

The function monitor (View > Function Monitor Window) is for basic troubleshooting. It displays a message each time an application calls a FairCom function.

Note

When the Function Monitor window is open, it significantly slows down the performance of the FairCom server so it can show you each function an application calls.

Figure 2. Function Monitor
Function Monitor


Start the FairCom server from the Windows command-line

  1. To run the FairCom server in the console tray without displaying the Control Window, find the TOOL_TRAY keyword in the ctsrvr.cfg file and disable it by putting a semicolon at the beginning of the line.

    ;CONSOLE TOOL_TRAY

  2. Run the FairCom server from the command line.

    C:\server> faircom ^&

  3. Observe that the FairCom server is running in the tool tray without displaying the user interface.

    Note

    It is a best practice for production deployments on Windows to run the FairCom server as a Windows Service. This ensures Windows keeps it running, and it allows administrators to easily manage the service remotely.

Start the FairCom server as a Windows services

Start the FairCom service using either the Microsoft sc.exe command or the Windows Services Control Panel applet.

  1. Open the Control Panel.

  2. Select the Services applet.

  3. Select the name of the FairCom servicef from the list of installed services.

  4. Click Start to start the service.

    Note

    Installing the FairCom server using the Windows Installer automatically makes it available to run as a Windows service. However, if you installed it by unzipping it into a folder, you will need to manually configure the FairCom server to run as a service.

Tool tray interface

When the server configuration file contains the CONSOLE TOOL_TRAY keyword, the FairCom server starts in the background, displaying only a FairCom DB icon in the Windows tool tray. This feature is especially nice for simple user sites, with no system administrative expert. Although more sophisticated sites will prefer running the FairCom server as a service, this feature gives a similar service-like background effect, without the user needing to learn Windows service administration.

  1. Navigate to and open the ctsrvr.cfg file.

  2. Add the keyword CONSOLE TOOL_TRAY.

    Note

    This keyword is not supported when the server is running as a service.

Example 2. Launch the server in background-tool-tray mode

The FairCom server for Windows accepts the & symbol, or the ^& for Windows server, as a command line parameter to execute in CONSOLE TOOL_TRAY mode.

C:\server>  ctreeace &

or

C:\server>  ctsrvr &


Tool tray interface

When the server configuration file contains the CONSOLE TOOL_TRAY keyword, the FairCom server starts in background, displaying only a FairCom DB icon in the Windows tool tray. This feature is especially nice for ‘simple’ user sites, with no system administrative expert. Although more sophisticated sites will prefer running the FairCom server as a service, this feature gives a similar ‘service-like’ background effect, without the user needing to learn Windows service administration.

Add the keyword CONSOLE TOOL_TRAY to your server configuration file, ctsrvr.cfg.

Note

This keyword is not supported when the server is running as a service.

The FairCom server for Windows accepts the ‘&’ symbol, or the "^&” for Windows server, as a command line parameter to execute in CONSOLE TOOL_TRAY mode.

Example 3. Launch the server in "background-tool-tray" mode
C:\server>  ctreeace &

or

C:\server>  ctsrvr &


Stop

In the /tools folder, run the command-line ctstop -AUTO to immediately shut down the FairCom server.

Stop the FairCom server on Windows

Note

If replication is running, it is advisable to stop replication before stopping the server. If replication is running, you may see error 792 (External server shutdown disabled), although replication should be able to handle an unexpected server shutdown. More information on the FairCom replication technology can be found in the Replication manager user guide.

  1. Windows service

    If the FairCom server is configured to run as a service on your machine, you can stop the service via the Windows Service Administrator or by issuing the net stop... command in a Command Prompt window.

  2.  Windows taskbar

    If the FairCom server was launched manually, a FairCom icon ( RunningIcon.png) appears in your taskbar. Right-click on the icon and select the appropriate shutdown option.

    shutdown_server.png

    Select the appropriate shutdown option

    This approach is normally used in demo and some development environments. In production environments, the FairCom server runs as a Windows service.

  3. FairCom console

    Exit the console application via the menu or the standard Windows "X" in the corner. If the FairCom server was launched manually, the console window can be displayed by double-clicking on the tool tray icon. Shut down the database engine using the console window’s Control menu.

    ControlMenuShutdown.png

    Console window Control menu

    This approach is normally used in demo and some development environments. In production environments, the FairCom server runs as a Windows service.

  4. ctadmn

    The ctadmn command-line utility provides an option to shut down the server. It works both when the server is running as a service and when it’s been launched manually. This tool only runs when supplied with an administrator user name and password.

  5. ctstop

    The stop utility can be used to shut down the server from the command-line or in a batch file. It can be used when the server is running as a service and when it’s been launched manually. This tool only runs when supplied with an administrator user name and password.

Stop the FairCom Windows service

The FairCom service can be stopped by using either the Microsoft sc.exe command or the Windows Services Control Panel applet, or the net stop command.

  • The service stops automatically when Windows signals the operating system itself is shutting down. A clean shutdown of Windows should result in a clean shutdown of the faircom server. However, since Windows only allows a 20 second delay for service shutdown, FairCom recommends all files be maintained under transaction processing to allow automatic recovery if cache cannot be safely flushed to prevent data corruption. The default 20 second delay can be adjusted using the WaitToKillServiceTimeout registry key, found in HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\, when present.

  • Windows Vista and later allow a new Service PRESHUTDOWN notification, which gives the service extra time to complete its shutdown. This can help to avoid a lengthy auto recovery if the server has too many cache pages to flush within the SHUTDOWN limit.

See Start for information about scripting the startup and shutdown operations on Linux.

Stop on Linux, Unix, and Mac

Linux, Unix, and MacOS users can use the included stop scripts to initiate a server shutdown. The script will be in <faircom>/server/stopserver.

Note

This script is provided as a "C" shell script and will work in most Unix shell environments. You are free to modify and tailor it to suit your local requirements.

Warning

These scripts must be run from the folder that contains them.

Other ways of stopping the FairCom server include:

  • ctadmn

    The ctadmn utility provides an option to shut down the server. It only runs with the administrator user name and password.

  • <faircom>\tools\ctstop

    The ctstop utility can shut down the server. It only runs with administrator user name and password.

  • The kill command

    An alternative way to stop the FairCom server is with the kill command. This command can be used in scripts if you include COMPATIBILITY TERMINATE_ON_SIGNAL in ctsrvr.cfg. The FairCom database engine traps the SIGSTOP signal.

    1. Use the ps command to find a process with faircom or ctree in the results.

    2. Kill any process that contains either faircom or ctree in the name.

    ps -e | grep faircom

    Note

    • If the FairCom server process is running, you will see it (see, Example 4, “Stop a script”).

    • Older versions of the FairCom products called the process "ctreesql" or "ctreeedge".

Example 4. Stop a script

Use "kill 7288" in this example.

7288 pts/0 00:00:06 faircom
#kill <faircom PID>


Transmission Control Protocol (TCP) is a standard networking protocol that allows computers to communication, see RFC 793.

Internet Protocol (IP) is the official Internet addressing scheme for uniquely identifies computers in network communications, see RFC 792. IP makes it possible to create networks of networks of computers.