How to Use the NFCMD Command Line Utility (Neverfail Heartbeat V4.7-5.5[n])

Follow

Summary

This Knowledgebase article provides information about how to use the NFCMD command line utility in Neverfail Heartbeat V4.7–V5.5[n].


More Information

The nfcmd utility can be used to connect to the Heartbeat server, issue a command, and wait for the command to complete or for a particular heartbeat event.


Procedure

Syntax

The command line syntax is:

nfcmd Host-or-ip Command [ Flags ]

where:

Host-or-ip Identifies the server running the Heartbeat service.
Command One of the Heartbeat server commands. See the list below.
Flags -e Event-to-wait-for
-t
Timeout-in-milliseconds
Event-to-wait-for If specified, the utility waits for the Heartbeat server to raise the event even if the command has completed.
If not specified, the utility waits for the command to complete.
The -e flag must be followed by the full class name of the event for example:

com.neverfail.newfilestatemgr.events.FileSystemCheckingDoneEvent

There should be no space between the -e flag and the event specified by Event-to-wait-for .
You can specify more than one –e option on the command line.
Timeout-in-millisecs Maximum number of millliseconds to wait for the command to complete or for events to be raised.
If the time limit is exceeded then the nfcmd utility finishes and returns an error status.

There should be no space between the -t flag and the value specified by Timeout-in-millisecs .

Commands

Any of the commands accepted by the nfclient utility can be issued using the nfcmd utility. The following table lists the common commands.

Versions v5.3.[n] and Earlier

start Starts replication.
Causes the protected applications to be started if they are not already going, and usually starts a full system check to ensure that the protected data is the same on passive and active servers.
stop Stops replication.
Stops application monitoring.
Stops the protected applications.
stopWOA Stops replication.
Stops application monitoring.
The protected applications are not stopped.
switch Switches active/passive roles.
The protected applications are stopped, the active server is made passive and the passive is made active, and the protected applications are restarted.
exit Stops replication and shuts down the Heartbeat service.
This may or may not stop the protected application depending on the server configuration. The behavior on stop can be configured using the Neverfail Heartbeat Management Client.
exitWOA Stops replication and shuts down the Heartbeat service.
The protected applications are not stopped.
exitForce Stops replication and shuts down the Heartbeat service.
The protected applications are stopped.
shutdown Same as exit .

Versions 5.4.[n]–5.5[n]

Controller.doStart Starts replication.
This causes the protected applications to be started if they are not already going, and usually will start a full system check to ensure that the protected data is the same on passive and active servers.
Controller.doStop Stops replication.
Stops application monitoring.
Stops the protected applications.
Controller.doStopWOA Stops replication.
Stops application monitoring.
The protected applications are not stopped.
Controller.doSwitch Switches active/passive roles.
The protected applications are stopped, the active server is made passive and the passive is made active, and the protected applications are restarted.
Controller.doExit Stops replication and shuts down the Heartbeat service.
This may or may not stop the protected application depending on the server configuration.
The behavior on stop can be configured using the Neverfail Heartbeat Management Client.
Controller.doExitWOA Stops replication and shuts down the Heartbeat service. The protected applications are not stopped.
Controller.doExitForce Stops replication and shuts down the Heartbeat service. The protected applications are stopped.
Controller.doShutdown Same as Controller.doExit .

Events

The Heartbeat service sends event messages to client utilities in response to commands or when it changes internal state. The following table lists some of the common events you might want to wait for when using the nfcmd utility.

com.neverfail.manager
.CommandCompleteEvent
The Heartbeat server fires this event when the command has started execution.

Note that this does not mean that the command has finished execution.

Some commands can take a long time to complete and will fire their own event when finished. See below.

This is the event that the nfcmd utility will wait for if no other event is specified using the –e flag.
com.neverfail.controller
.ControllerStartCmdCompleteEvent
Fired when the start (or Controller.doStart ) operation has completed.
com.neverfail.controller
.ControllerSwitchCmdCompleteEvent
Fired when the switch (or Controller.doSwitch ) operation has completed.
com.neverfail.controller
.ControllerStopCmdCompleteEvent
Fired when the stop (or Controller.doStop ) operation has completed.
com.neverfail.nfchannel
.NFChannelConnectedEvent
Fired when the comms channel between active and passive servers becomes connected.
com.neverfail.newfilestatemgr.events
.FileSystemCheckingStartedEvent
Fired when the verification of file data begins.
com.neverfail.newfilestatemgr.events
.FileSystemCheckingDoneEvent
Fired when the verification of file data is finished.
com.neverfail.registry.state.events
.RegistryCheckingStartedEvent
Fired when the verification of registry data begins.
com.neverfail.registry.state.events
.RegistryCheckingDoneEvent
Fired when the verification of registry data is finished.
Comments

The nfcmd utility connects to the Heartbeat server and logs in using the credentials of the currently logged in user. By default, the Heartbeat service allows administrators on the local server to log on using nfcmd and execute commands. If you are not using an administrator account, or you are running nfcmd on another server, then you will have to register the hostname and user name you want to use when running nfcmd . To register, you can run the nfcmd utility on the local server and issue the AddUser command, like this:

nfcmd localhost addTrustedClient myHostIP myUserName myPrivs

where:

myHostIP The IP address of the client system you want to use when running the nfcmd utility.
myUserName The user name of the user running the nfcmd utility on the client system.
myPrivs administrator , operator or monitor

For example, to allow user tom on the system with the IP 192.168.99.100 , you could run the following command on the server where the Heartbeat service is running:

nfcmd localhost addTrustedClient 192.168.99.100 tom administrator

User tom can then use nfcmd running on the system with the IP 192.168.99.100 to send commands to the Heartbeat service.

The Heartbeat service runs on both active and passive servers. Normally whichever server is active will be reachable using the principal (public) IP address – that is, the IP address that clients of the protected applications use to connect to the protected applications. Sometimes the two servers will be reachable using other IP addresses. The nfcmd utility can use any of the reachable addresses to send commands to the Heartbeat service. The major commands listed above will have the same effect when issued to either one of a connected pair of Heartbeat servers.

Examples

  1. nfcmd localhost stopWOA (in V5.3.[n] and earlier) or nfcmd localhost Controller.doStopWOA (in V5.4.[n]–V5.5[n])
    Stop replication. Leave the protected applications running. Leave the Heartbeat service running.


  2. nfcmd localhost start -ecom.neverfail.newfilestatemgr.events.FileSystemCheckingDoneEvent –t60000 (in V5.3.[n] and earlier) or
    nfcmd localhost Controller.doStart -ecom.neverfail.newfilestatemgr.events.FileSystemCheckingDoneEvent -t60000 (in V5.4.[n]–V5.5[n])
    Start replication. Start the protected applications if they’re not already running. Wait for up to 60 seconds for the file system check to finish.

Return Codes

The nfcmd utility returns a status value when it completes. If you use nfcmd in a batch script, you may want to check the return code to see if the operation was successful. A batch script can check the return code using the if [not] errorlevel <number> then… command or by reading the %errorlevel% environment variable immediately after executing the nfcmd utiltity. Consult the DOS command documentation before use – note in particular that if errorlevel <number> returns true if errorlevel >= <number>.

The following table lists the return codes:

0 Command completed successfully.
21 Command completed successfully and the event used in the –e command line option was returned.
-4 The value specified in the –t command line option is not valid. The following message will be written to stderr: "Unable to convert the timeout provided into a number :"
-2 The event specified in the –e command line option is not valid. The following message will be written to stderr: "You specified an event as an argument using the -e flag which could not be resolved into a class : "
2 The command used is not valid.
3 An invalid number of command line arguments were provided. This could mean the hostname has not been specified correctly, or that not enough parameters were provided for the command specified. The following message will be written to stderr: "Not enough arguments provided"
4 The connection with the server was lost while attempting to execute the command.
5 The server was asked to shutdown before the command completed.
6 An exception occurred while the command was executing.
8 The timeout period was exceeded before the command completed.
11

nfcmd was unable to login into the server identified by the hostname and the following message will be displayed on stderr "Invalid username/password" . Check that the hostname and account used when running nfcmd is registered using the addTrustedClient command.


Applies To

Neverfail Heartbeat V4.7–5.5[n]


Related Information

Knowledgebase Article # 1866 , How to Use the NFCMD Command Line Utility (Neverfail Heartbeat V6.0 and Newer).

KBID-442

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.