Communication Protocol Reference Guide

This Wiki is deprecated and we are are currrently migrating remaining pages into product documentation (Admin Guide, NXSL Guide)

= Introduction =

NetXMS Communication Protocol (NXCP) is a protocol used by all NetXMS entities (server, agents, clients) for communications. Protocol is message-oriented and designed to work on top of TCP protocol.

Message Format

Message Structure

Message in NXCP consists of a header and an optional payload which follows header immediatelly. Padding bytes can be added at the end of a message to make it aligned to 8-bytes boundary. Here is general message structure:

Header 16 bytes

Payload 0 – 256K bytes

Padding 0-7 bytes

Message Header

Header have the following format:

Field	Size (bytes)	Meaning
CODE	2	Command code. List of well-known command codes can be found in Appendix A.
FLAGS	2	Flags – see explanation below
SIZE	4	Size of a message in bytes, including header and padding
ID	4	Message identifier (usually used to match replies to requests)
DF_COUNT	4	Number of data fields or size of raw data, depending on flags

In the FLAGS field, the following bit flags (or combination of them) can be used:

Flag	Value	Meaning
BINARY	0x0001	Message contains raw binary data instead of structured data fields. If this flag is set, DF_COUNT contains size of raw data in bytes.
END_OF_FILE	0x0002	For file transfer operations, indicates that message contains last part of a file.
DONT_ENCRYPT	0x0004	Used internally by libnetxms to indicate that message should not be encrypted on sending. Has no meaning for the receiver.
END_OF_SEQUENCE	0x0008	Indicates that message contains last portion of data.
REVERSE_ORDER	0x0010	Indicates that data coming in a set of messages will arrive in reverse order (event log records, for example).
CONTROL	0x0020	Indicates control message. Control messages doesn't contain payload part, and header fileds may have special meaning. See below for detailed control messages list.

All fileds have network byte order.

Data Element (Variable)

Structured message's payload consist of one or more data elements, or variables. Each variable has the following structure:

Variable ID 4 bytes

Data Type 1 byte

Padding 1 byte

Data 0-256K bytes (depending on data type)

Padding 0-7 bytes

Size of each element should be a multiplier of 8, so up to 7 padding bytes can be appended as necessary.

Variable ID is a unique identifier of a variable in a message scope. List of well-known message ID's can be found in Appendix B.

Data type can be one of the following:

Symbolic name	Value	Description
INTEGER	0	32-bit integer value
STRING	1	String value
INT64	2	64-bit integer value
INT16	3	16-bit integer value
BINARY	4	Raw binary data
FLOAT	5	64-bit floating point value

All numeric values have network byte order.

Actual format of data filed determined by variable's data type – see below.

INTEGER

Padding 2 bytes

Integer value (32-bit) 4 bytes

STRING

Padding 2 bytes

Length 4 bytes

Content 0 – 256K bytes

Strings encoded in two-byte UNICODE (UCS-2), with network byte order. Length specified in bytes.

INT64

Padding 2 bytes

Integer value (64-bit) 8 bytes

INT16

Integer value (16-bit) 2 bytes

BINARY

Padding 2 bytes

Length 4 bytes

Content 0 – 256K bytes

FLOAT

Padding 2 bytes

Floating point value (64-bit) 8 bytes

Client-Server Communications

General Description

Communication session between client and server always initiated by client. All messages can be divided into three categories – request, response, and notification. Request messagess sent by client to ask server for information or to instruct it to do something. Server replies with response messages, which usually contains request completion code and, depending on request, some additional data. If amount of data to be transferred is large, server may send many response messages to one request. Server may also send notification messages to inform client about various events – for example, change in object's status.

Typical client-server session scenario

Usually client-server communication session looks as following:

Client message	Server message
CMD_GET_SERVER_INFO
	CMD_REQUEST_COMPLETED
CMD_LOGIN
	CMD_LOGIN_RESP
Data request or command
	CMD_REQUEST_COMPLETED
...

Request messages

CMD_CONFIG_GET_CLOB

Get value of configuration variable containing large string.

Variables

Variable	Type	Description
VID_NAME	STRING	Variable name

Response: CMD_REQUEST_COMPLETED with VID_VALUE set to variable's value.

CMD_CONFIG_SET_CLOB

Set value of configuration variable containing large string.

Variables

Variable	Type	Description
VID_NAME	STRING	Variable's name.
VID_VALUE	STRING	Variable's value.

Response: CMD_REQUEST_COMPLETED

CMD_GET_LAST_VALUES

Get latest values of all DCIs for given node.

Variables

Variable	Type	Description
VID_OBJECT_ID	INTEGER	Node's identifier.

Response: CMD_REQUEST_COMPLETED with appropriate variables set (see description for CMD_REQUEST_COMPLETED message for details).

CMD_GET_SERVER_INFO

Get server information.

Response: CMD_REQUEST_COMPLETED

CMD_KEEPALIVE

This message only cause server to immediatelly respond with successfull request completion message. It can be used to check connectivity with server or to prevent current connection from timing out.

Response: CMD_REQUEST_COMPLETED

CMD_LOGIN

Perform user login.

Variables

Variable	Type	Description
VID_LOGIN_NAME	STRING	Login name
VID_AUTH_TYPE	INT16	Authentication type: 0 for password authentication or 1 for authentication by certificate
VID_PASSWORD	STRING	Password (ignored if authentication type is 1)
VID_SIGNATURE	BINARY	User's signature – server's challenge encrypted with user's private key (ignored if authentication type is 0)
VID_CERTIFICATE	BINARY	User's certificate (ignored if authentication type is 0)
VID_CLIENT_INFO	STRING	Client application name and version
VID_OS_INFO	STRING	OS name and version (like WinNT 5.0)
VID_LIBNXCL_VERSION	STRING	Version of libnxcl

Response: CMD_LOGIN_RESP

Response Messages

CMD_LOGIN_RESP

Response message for login request (CMD_LOGIN).

Variables

Variable	Type	Description
VID_RCC	INTEGER	Request completion code. For list of possible codes see Appendix C.
VID_USER_ID	INTEGER	User ID of logged in user.
VID_USER_SYS_RIGHTS	INTEGER	System-wide access rights for logged in user.
VID_CHANGE_PASSWD_FLAG	INT16	Password change flag – will be set to non-zero if user should change password.
VID_DBCONN_STATUS	INT16	Status of connection between server and backend database – will be set to non-zero value if backend database connection has problems.

CMD_REQUEST_COMPLETED

Generic response message – used as a response to most of the requests.

Variables

Variable	Type	Description
VID_RCC	INTEGER	Request completion code. For list of possible codes see Appendix C.
VID_LOCKED_BY	STRING	Current lock owner. Valid only if VID_RCC is set to RCC_COMPONENT_LOCKED.

In the following subsections described additinal variables specific to request messages.

For CMD_CONFIG_GET_CLOB

Additional variables used only in response to CMD_CONFIG_GET_CLOB message

Variable	Type	Description
VID_VALUE	STRING	Configuration variable's value.

For CMD_CREATE_MAP

Additional variables used only in response to CMD_CREATE_MAP message

Variable	Type	Description
VID_MAP_ID	INTEGER	ID assigned to created map.

For CMD_GET_LAST_VALUES

Additional variables used only in response to CMD_GET_LAST_VALUES message

Variable	Type	Description
VID_NUM_ITEMS	INTEGER	Number of DCIs.
VID_DCI_VALUES_BASE		List of DCIs, see below.

Variables for DCI values starts at VID_DCI_VALUES_BASE and each DCI represented by 10 variables (i.e. first DCI data will start at VID_DCI_VALUES_BASE, second at VID_DCI_VALUES_BASE + 10, and so on). Structure of each 10-variables group is following:

Variable at offset	Type	Description
0	INTEGER	DCI ID
1	STRING	Name
2	STRING	Description
3	INT16	Source (origin)
4	INT16	Data type
5	STRING	Current value
6	INTEGER	Timestamp
7	INT16	Status
8..9		Reserved

For CMD_GET_SERVER_INFO

Additional variables used only in response to CMD_GET_SERVER_INFO message

Variable	Type	Description
VID_SERVER_ID	BINARY	8-byte server identifier.
VID_SERVER_VERSION	STRING	Server version string.
VID_PROTOCOL_VERSION	INTEGER	Client-server protocol version.

Appendix A. Well-known Message Codes

Symbolic name	Value
CMD_LOGIN	0x0001
CMD_LOGIN_RESP	0x0002
CMD_KEEPALIVE	0x0003
CMD_EVENT	0x0004
CMD_GET_OBJECTS	0x0005
CMD_OBJECT	0x0006
CMD_DELETE_OBJECT	0x0007
CMD_MODIFY_OBJECT	0x0008
CMD_OBJECT_LIST_END	0x0009
CMD_OBJECT_UPDATE	0x000A
CMD_GET_EVENTS	0x000B
CMD_EVENT_LIST_END	0x000C
CMD_GET_CONFIG_VARLIST	0x000D
CMD_SET_CONFIG_VARIABLE	0x000E
CMD_GET_OBJECT_TOOLS	0x000F
CMD_EXECUTE_ACTION	0x0010
CMD_DELETE_CONFIG_VARIABLE	0x0011
CMD_NOTIFY	0x0012
CMD_TRAP	0x0013
CMD_OPEN_EPP	0x0014
CMD_CLOSE_EPP	0x0015
CMD_SAVE_EPP	0x0016
CMD_EPP_RECORD	0x0017
CMD_LOCK_EVENT_DB	0x0018
CMD_UNLOCK_EVENT_DB	0x0019
CMD_SET_EVENT_INFO	0x001A
CMD_EVENT_DB_RECORD	0x001B
CMD_LOAD_EVENT_DB	0x001C
CMD_REQUEST_COMPLETED	0x001D
CMD_LOAD_USER_DB	0x001E
CMD_USER_DATA	0x001F
CMD_GROUP_DATA	0x0020
CMD_USER_DB_EOF	0x0021
CMD_UPDATE_USER	0x0022
CMD_DELETE_USER	0x0023
CMD_CREATE_USER	0x0024
CMD_LOCK_USER_DB	0x0025
CMD_UNLOCK_USER_DB	0x0026
CMD_USER_DB_UPDATE	0x0027
CMD_SET_PASSWORD	0x0028
CMD_GET_NODE_DCI_LIST	0x0029
CMD_NODE_DCI	0x002A
CMD_NODE_DCI_LIST_END	0x002B
CMD_DELETE_NODE_DCI	0x002C
CMD_MODIFY_NODE_DCI	0x002D
CMD_UNLOCK_NODE_DCI_LIST	0x002E
CMD_SET_OBJECT_MGMT_STATUS	0x002F
CMD_CREATE_NEW_DCI	0x0030
CMD_GET_DCI_DATA	0x0031
CMD_DCI_DATA	0x0032
CMD_GET_MIB_TIMESTAMP	0x0033
CMD_GET_MIB	0x0034
CMD_REQUEST_NEW_LPP_ID	0x0035
CMD_OPEN_LPP	0x0036
CMD_CREATE_OBJECT	0x0037
CMD_GET_EVENT_NAMES	0x0038
CMD_EVENT_NAME_LIST	0x0039
CMD_BIND_OBJECT	0x003A
CMD_UNBIND_OBJECT	0x003B
CMD_GET_IMAGE_LIST	0x003C
CMD_LOAD_IMAGE_FILE	0x003D
CMD_IMAGE_LIST	0x003E
CMD_IMAGE_FILE	0x003F
CMD_AUTHENTICATE	0x0040
CMD_GET_PARAMETER	0x0041
CMD_GET_LIST	0x0042
CMD_ACTION	0x0043
CMD_GET_DEFAULT_IMAGE_LIST	0x0044
CMD_DEFAULT_IMAGE_LIST	0x0045
CMD_GET_ALL_ALARMS	0x0046
CMD_GET_ALARM	0x0047
CMD_ACK_ALARM	0x0048
CMD_ALARM_UPDATE	0x0049
CMD_ALARM_DATA	0x004A
CMD_DELETE_ALARM	0x004B
CMD_LOCK_ACTION_DB	0x004C
CMD_UNLOCK_ACTION_DB	0x004D
CMD_LOAD_ACTIONS	0x004E
CMD_ACTION_DB_UPDATE	0x004F
CMD_MODIFY_ACTION	0x0050
CMD_CREATE_ACTION	0x0051
CMD_DELETE_ACTION	0x0052
CMD_ACTION_DATA	0x0053
CMD_GET_CONTAINER_CAT_LIST	0x0054
CMD_CONTAINER_CAT_DATA	0x0055
CMD_DELETE_CONTAINER_CAT	0x0056
CMD_CREATE_CONTAINER_CAT	0x0057
CMD_MODIFY_CONTAINER_CAT	0x0058
CMD_POLL_NODE	0x0059
CMD_POLLING_INFO	0x005A
CMD_COPY_DCI	0x005B
CMD_WAKEUP_NODE	0x005C
CMD_DELETE_EVENT_TEMPLATE	0x005D
CMD_GENERATE_EVENT_CODE	0x005E
CMD_LOCK_TRAP_CFG	0x005F
CMD_UNLOCK_TRAP_CFG	0x0060
CMD_CREATE_TRAP	0x0061
CMD_MODIFY_TRAP	0x0062
CMD_DELETE_TRAP	0x0063
CMD_LOAD_TRAP_CFG	0x0064
CMD_TRAP_CFG_RECORD	0x0065
CMD_QUERY_PARAMETER	0x0066
CMD_GET_SERVER_INFO	0x0067
CMD_SET_DCI_STATUS	0x0068
CMD_FILE_DATA	0x0069
CMD_TRANSFER_FILE	0x006A
CMD_UPGRADE_AGENT	0x006B
CMD_GET_PACKAGE_LIST	0x006C
CMD_PACKAGE_INFO	0x006D
CMD_REMOVE_PACKAGE	0x006E
CMD_INSTALL_PACKAGE	0x006F
CMD_LOCK_PACKAGE_DB	0x0070
CMD_UNLOCK_PACKAGE_DB	0x0071
CMD_ABORT_FILE_TRANSFER	0x0072
CMD_CHECK_NETWORK_SERVICE	0x0073
CMD_GET_AGENT_CONFIG	0x0074
CMD_UPDATE_AGENT_CONFIG	0x0075
CMD_GET_PARAMETER_LIST	0x0076