How to Use the NFCMD Command Line Utility (Neverfail Heartbeat V6 and Later)

Follow

Summary

This Knowledgebase article provides information about how to use the NFCMD command line utility in Neverfail Heartbeat V6 and Later.

 

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 [ Arguments ][ Flags ]

where:

Parameter Details
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 milliseconds 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 and their forms in each version.

V5.5[.n] and Earlier
Command
V6.0[.n] and More Recent
Command Argument(s)
Controller.doStart StartReplication withApplications
Controller.doStop StopReplication withApplications
Controller.doStopWOA StopReplication withApplications
Controller.doSwitch MakeActive newActive , optimizeHighBWSwitch
Controller.doExit Shutdown serverList , withApplications
ShutdownAll withApplications
Controller.doExitWOA
Controller.doExitForce
Controller.doShutdown

The following table describes the commands, including new commands, in Versions 6.0.[n] and later.

Command Details
MakeActive MakeActive newActive , optimizeHighBWSwitch

If replicating and the newActive server is synchronized with the currently active server, makes the selected server the active server, then starts replication (in sync if possible) from new active server.

If not replicating, the command changes the active server from the current to the new active.

The newActive parameter indicates the server that is to be made the active server, and must be one of PRIMARY or SECONDARY or TERTIARY. The newActive server must be a member of the partition to which the client issuing the command is connected.

The optimizeHighBWSwitch parameter indicates whether a switch between two servers connected via a high-bandwidth channel (Primary, Secondary) should be optimized by dropping pending updates for the remaining server (Tertiary) and requiring a subsequent resynchronization of the remaining server. The optimizeHighBWSwitch parameter only has an effect where the switch is between Primary Active and Secondary (or vice-versa) and the Tertiary server is also in sync.

Example:
nfcmd localhost MakeActive SECONDARY false
previewMakeActive This command uses the same parameters as the MakeActive command above but instead of executing the command, it will show the plan for what will occur when MakeActive is executed
AutoSwitch AutoSwitch reason

Shuts down (in sync) Heartbeat running on the active server.
Stops replication.
Makes active the first passive (next in the replication chain).

This is effectively a MakeActive operation for the first passive (first in the replication chain after the Active). It normally is initiated by an agent such as the public network monitor or AMF because they have determined that the currently active server should no longer remain active. This command can also be initiated from NFClient or NFCmd for testing.

· The first passive must be in synch with the active.
· The first passive must be a permitted failover target from the active.

Example:
nfcmd localhost AutoSwitch "Testing autoswitch"
StartReplication StartReplication withApplications

Starts replication from the active server to the other servers with a full-system check.
The other servers transition from inert to passive.
Application monitoring begins on the passive servers.
If withApplications is true, the actions to start applications are performed on the active server.
The replicating state is persisted.

· Attempting to start replication when already replicating results in an exception being raised.

Example:
nfcmd localhost StartReplication true
StopReplication StopReplication withApplications

Stops replication from the active server to the other servers.
If withApplications is true, applications are stopped on the active server and replication is stopped in-sync if possible.
The passive servers transition to being inert.
Application monitoring will stop on the inert servers.
The not-replicating state will be persisted through shutdown and start-up of Heartbeat.

· Attempting to start replication when already replicating will result in an exception being raised.

Example:
nfcmd localhost StopReplication false
Shutdown Shutdown serverList , withApplications

Shuts down Heartbeat on the specified set of servers.

This is the successor to the exit , exitWoA commands. If the active server is among those shut down, the remaining servers are left as inert (passive and not replicating). Shutting down a passive server at the end of the replication chain simply removes it. Shutting down a server in the middle of the replication chain causes the chain to be reformed. The withApplications parameter is acted upon only if the active server is being shut down. If withApplications is true then applications are stopped on the active server, and replication is stopped in-sync if possible.

Example:
nfcmd localhost Shutdown "SECONDARY,TERTIARY" false
ShutdownAll ShutdownAll withApplications

This is an alias for shutdown specifying all member servers.

Example:
nfcmd localhost ShutdownAll false

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.

Event Explanation
com.neverfail.manager
.CommandCompleteEvent
The Heartbeat server fires this event when the command has started execution.
Note: 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.

NFCMD monitoring usage

NFCMD commands can be used to show the current state of the Neverfail cluster and applications. The following are examples:

Information about the cluster state:

nfcmd localhost getSingleProperty Controller GroupType   

- Identifies the cluster as binary (Primary and Secondary pair) or ternary (Primary, Secondary, and Tertiary)

nfcmd localhost getSingleProperty Controller Host  

- Displays the server's identity

nfcmd localhost getSingleProperty Controller ActiveServer 

- Identifies the active server

nfcmd localhost getSingleProperty Controller Chain   

- Identifies the replication chain, for example [Primary > Secondary > Tertiary] or [Secondary > Primary > Tertiary]

nfcmd localhost getSingleProperty Controller SummaryClusterState  

-  Displays the replication chain and synchronization status between peers. It can be interpreted as:

==>  link replicating in synch

=/=> link replicating not in synch

---  link not replicating

nfcmd localhost getSingleProperty Controller ReplicationEnabled  

- Is the replication enabled? Result = true/false

Information about the application state:

nfcmd localhost getSingleProperty AMFramework ApplicationsHealth  

- Displays the application health  status. It can be interpreted as:

  • OK - all services, rules ok.
  • PotentialProblem  - A potential problem has been encountered - A performance threshold has been exceeded but not for the full duration
  • Warning  - A performance threshold has been consistently above the threshold.
  • Critical - The application is no longer providing service to clients.
  • Unknown - Unknown application health
  • Unmonitored - The application is not monitored
nfcmd localhost getSingleProperty AMFramework ApplicationsState  

- Displays the on of the following application states:

  • Stopped
  • Started
  • Starting
  • Stopping

Adding a new replication filter

nfcmd localhost AMFramework.doAddUserSponsoredInclusionFileFilter "c:\protected\**"

Note: The above monitoring commands will only work for Neverfail Heartbeat v6.2 and later.

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:

Parameter Details
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.



  1. 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:

Status Explanation
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 V6.0.[n] and later

 

Related Information

Knowledgebase Article # 442 , How to Use the NFCMD Command Line Utility (Neverfail Heartbeat V4.7–5.5[n]).

 

KBID-1866

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.