Service Command

Command Purpose

The service command is used to view and control the status of services across the cluster.

Command Syntax

Show Service Status

Information about the configured, running service instances can be retrieved using the status action:

service status [filter]

The output produced by this command contains:

• The name of the node that the service instance is running on.
• The internal type of the service.
• The configured service name.
• The service instance’s number.
• The time the service instance was first started.
• The time that the most recent heartbeat from the service instance was received.
• The service instance’s current status.
• The service instance’s last status.

If required, an optional filter string can be supplied to the command. Only service instances that have a node name, service name, instance number, or status that matches the filter will be displayed. The match is case-insensitive.

Start Service

New instances of a configured service can be started on a given node using the start action:

service start <service> <node>

The service parameter is a service name. It specifies the service to start. The corresponding service must have been configured on the node specified by node.

The node parameter is a node name. It specifies the node on which service is configured and should be started.

Both service and node are case-sensitive.

This command will start as many additional instances of service as are configured on node, regardless of how many instances of service are already running. Existing instances of service will be unaffected by this command.

The new instances of service will be started with the configuration specified in the configuration file.

No output is returned from this command unless an error is encountered.

Stop Service

Running service instances can be stopped using the stop action:

service stop <service> [node]

The service parameter is a service name or instance identifier. It specifies the service or service instance to stop.

The optional node parameter is a node name. If specified, only service instances running on the specified node will be affected by the command.

Note that node may only be specified if service is a name rather than a service instance identifier. This is because service instance identifiers uniquely identify service instances within the cluster.

The system will prompt for confirmation if service is a service name and node is not specified.

No output is returned from this command unless an error is encountered.

Reload Service

The reload action can be used to instruct running service instances to load and apply fresh configuration from their node’s configuration file:

service reload <service> [node]

The service parameter is a service name or instance identifier. It specifies the service or service instance that should reload its configuration.

The optional node parameter is a node name. If specified, only service instances running on the specified node will be affected by the command.

Note that node may only be specified if service is a name rather than a service instance identifier. This is because service instance identifiers uniquely identify service instances within the cluster.

The system will prompt for confirmation if service is a service name and node is not specified.

All endpoints owned by the target service will also reload their configuration. Endpoints may be enabled, disabled, or disabled then re-enabled as a consequence.

No output is returned from this command unless an error is encountered.

Error Messages

Invalid Syntax

ERROR: action must be supplied.

The service command always requires an action parameter to be supplied.

ERROR: action and service must be supplied.

The service stop and service reload commands require at least action and service to be supplied.

ERROR: action, service, and node must be supplied.

The service start command requires at least action, endpoint, and service to be supplied.

ERROR: too many arguments

The service command expects a limited number of arguments for each action. Note that node cannot be specified if service is a service instance identifier.

ERROR: unknown action '<action>'.

The service command only accepts certain action keywords. Review the available actions and alter the input.

ERROR: no input received.

Confirmation prompts require input.

Command Failure

ERROR: failed to send request to manager service.

The command could not be sent to a manager service for handling. Ensure that a manager service is running on the target node. Contact N-Squared technical support if problems persist.

ERROR: service status request was unsuccessful: <reason>

The service status command failed for the given reason. Review the reason given. Contact N-Squared technical support if problems persist.

ERROR: service start request was unsuccessful: <reason>

The service start command failed for the given reason. Review the reason given. Contact N-Squared technical support if problems persist.

ERROR: failed to send request to service instance '<service>'.

The command could not be sent to the target service instance for handling. Ensure that the target service instance is running in the cluster. Contact N-Squared technical support if problems persist.

ERROR: failed to send request to service '<service>'.

The command could not be sent to the target service for handling. Ensure that the target service is running on at least one node in the cluster. Contact N-Squared technical support if problems persist.

ERROR: failed to send request to node '<node>' service '<service>'.

The command could not be sent to the target service for handling. Ensure that the target service is running on the target node. Contact N-Squared technical support if problems persist.