Config entries and internal data points

Entry

Type

Default

Range

Meaning

agentDPName

string

SNMPAgent

-

This entry specifies the middle part of the data point name for the SNMP agent DPs. Each name is composed of _driverNumber_agentDPName_agentNumber.

The data points are of the internal type _SNMPAgent.

agentDPTemplate

string

_SNMPAgent

-

In order to initialize all data point elements a template data point is queried when starting a driver. The elements of this data point are available for all data points. If an element of this template data point is missing, the element is not available on any agent data points! A template data point can, of course, be a normal data point (that is used anyway). In this case the value is set to the complete data point name e.g.  _1_SNMPAgent_5.

ctrlDPName

string

SNMPManager

-

This string specifies which string is used as a part of the manager Control data point. Operating states of the driver are shown via this data point. The name of the data point also contains the number of the driver.

_driverNumber_ctrlDPName

agentAliveTimeout

uint

40

-

The interval for cyclic connection monitoring (connection to the agents)  is set via this entry. (in seconds)

Note

The aliveCheck is performed through querying the MIB base address.

agentConnectTimeout

int

60

-

The connection to the SNMP agent is monitored via this entry. This entry is valid for all agents that are queried by a driver. If this timeout elapses (specification in seconds)without receiving a message from the agent, a bit in the agent data point is set. When the next message is received the bit is deleted. Each received message resets the timer.

agentConnectOID

string

"1.3.6.1.2.1.1.1.0" (system.sysDescr)

-

Before a ConnectTimeout is triggered for an agent, the driver tries to query the OID that is specified here and thus tries to receive an answer from the agent. The value of this query is discarded. If the query is not successful the timeout takes effect. The OID specified here is valid for all agents of the driver.  Alternatively  ”1.3.6.1.2.1.1.3.0” (system.sysUpTime) could be used.

enableTraps

string

”Yes”

"Yes"|"No"

If the SNMP manager should receive traps, this entry should be set to ”Yes”. If you do not want to receive traps, set the entry to ”No”. The received traps are shown in the manager data point.

delayBetweenAgents

int

0

>= 0

Defines the time interval between the queries to the grouped agents in milliseconds. The default value 0 means that the queries within a poll group are sorted and also executed in this ordered. If a value >0 is set, the changed agents will be grouped according to the entry numberOfAgentsWithDelay and queried after the defined time interval (delayBetweenAgents).

If an agent is not accessible, it may happen that the other agents can not be queried. If a request to an agent answers with a timeout, all requests of this agent will be deleted (if the option "set to invalid" is enabled, the deleted requests will be set to invalid). This is only done when the config entry "delayBetweenAgents" is set. In the next poll cycle the driver will again attempt to establish a connection to this.

numberOfAgentsWithDelay

uint

1

0 - 500

If  "delayBetweenAgents" is set to =>0 several agents can communicate at the same time. This config entry defines the number of the agents.

doGQOnStart

string

”Yes”

"Yes"|"No"

This parameter specifies that all configured SNMP objects are queried when the driver is started. (Default) This option can cause a selective overload of the network since all configured objects are queried. If a general query should not be executed set the entry to "No".

In order to avoid too high network load when doGQOnStart = ”Yes” is used, it is also possible to execute general queries on single agents via the internal data point _Driver<Nr>.GQ:_original.._value. For more information see General query.

ignoreGQTrapErrors

string

"No"

"Yes"|"No"

If a general query is performed OIDs, which exist only as traps and no as OID objects, and those are spontaneous addresses, this config entry prevents that invalid bit is set to the specific DPE.

mapInvalidData

string

”Yes”

"Yes"|"No"

If this config entry is set to ”Yes”, the invalid bit is set for DPEs with an input address when the connection to the corresponding SNMP agent is lost.

maxAgents

uint

255

>= 0

Number of the possible configurable SNMP Agents. Per default the limitation is 255 SNMP Agents.

maxNumOfVbsInBulkQuery

uint

1000

>= 0

Usually a device returns a "endOfMIBView" at the last SNMP address (OID) of a bulk query  which will cancel the query.  If this may not be the case for some reason, the driver will restart at the beginning of the list and is stuck in an infinite loop. In order to avoid this, the query will be canceled when the first already received result is repeated. For additional security measures, a limited number of results can be set with this config entry. When the given number is hit, the query will be canceled.

maxTrapsPerSecond

uint

50

>= 0

Defines the maximum number of traps, which are sent per second. If the value was set to <=0 a warning will be written to the log. In case of an over load, the traps are buffered. The buffer size is defined in the config entry maxTrapsBufferSize.

maxTrapsBufferSize

uint

30000

>= 0

Defines the buffer size to buffer traps which could not be sent due to an overload (limited with maxTrapsPerSecond).

onlyActivePolls

string

"No"

"Yes"|"No"

If onlyActivePolls is set to "Yes", only the active driver polls in a redundant system. "No" means that both drivers poll the agent.

reportHomelessTraps

int

0

0|1

Defines if the information for homeless traps shall be written to the internal data point (see Trap.HomelessTrap).

• 0 => Information will be written to the LogViewer.

• 1 => Information will be written to the LogViewer and to the internal data point.

• 2 => Information will be written to the LogViewer and to the internal data point but only if at least one payload OID could not be matched to a peripheral address.

trapReceptionPort

int

162

-

You can set the trap port for the SNMP driver. The default port is 162.

useExtendedEngineID

string

"N"

"Y"|"N"

Defines whether the internal EngineID of the SNMP agent will be extended with the regarding host and port information.

Entry

Type

Default

Range

Meaning

v3entityDPName

string

"SNMPV3Entity"

-

This entry specifies the middle part of the data point name for the SNMP V3 entity DPs.

Each name consists of _driverNumber_v3entityDPName_agentNumber.

The entity number is thereby automatically tested from 0 to 255. This means that each new entity gets another number. The detailed meaning of the entity can be described in the comment. The mentioned data points are of internal type  _SNMPV3Entity.

Default: SNMPV3Entity

v3entityDPTemplate

string

"_SNMPV3Entity"

-

In order to initialize all data point elements a template data point is queried at the start of the driver. Its leaves are then available for all data points. If an element of this template data point is missing, it is not available on the registered agent data points!

As template data point also a "normal" data point that is used anyway can be used. In this case the value is set to the complete DP name e.g. _1_SNMPV3Entity_5.

Default: _SNMPV3Entity.

setTimeoutOnV3USMerrors

string

"No"

"Yes"|"No"

If setTimeoutOnV3USMerrors = "yes" and a state timeout was set for an SNMPv3 agent, USM error have an impact on the state of the timeout.

"yes" - in case of a USM error, the DPE Status.Timeout will be set to TRUE.

"no" - the DPE Status.Timeout will never be set to TRUE in case of a USM error.

snmpDir

string

"/<projectdirectory>/data"

-

For SNMPv3 the SNMP entity needs a boot counter. This is located in the snmpv3_boot_counter file.

Per default the SNMP driver writes this file into the /data directory from the project directory. If the user has no write access at this directory, so another directory can be set via this config entry.

Entry

Type

Default

Range

Meaning

SNMPPortNr

int

4701

1  -  65535

Specifies the port number of the Live agent.

enableUserTraps

string

Yes

"Yes"|"No"

If this option is activated, own texts can be sent as traps via the Live agent data point. As already mentioned the Pmon agent is needed as a proxy.

v1ReadCommunity

string

”public”

-

Defines the ReadCommunity for SNMP v1/v2. Used for the agents that are connecting to the WinCC OA system.

v1WriteCommunity

string

”admin”

-

Defines the WriteCommunity for SNMP v1/v2. Used for the agents that are connecting to the WinCC OA system.

snmpDir

string

"<project_directory>/data"

-

For SNMPv3 the SNMP entity needs a boot counter. This is located in the "snmpv3_boot_counter" file.

Per default the SNMP Live Agent writes this file into the /data directory from the project directory. If the user has no write access at this directory, so another directory can be set via this config entry.

PmonPortNr

int

4700

1  -  65535

Specifies the port number of the Pmon. This is necessary since the Pmon serves as a proxy for the Live Agent.

Entry

Type

Default

Range

Meaning

SNMPPortNr

int

4700

1  -  65535

Port number for which the Pmon is enabled for SNMP requests.

sendManagerStateChange

string

No

"Yes"|"No"

If a trap should be sent when the status of a manager is changed, this parameter should be set to ”Yes”.

allowSNMP

string

No

"Yes"|"No"

Defines if WCCILpmon also opens the SNMP port and therefore reacts to SNMP requests.

v1ReadCommunity

string

”public”

-

Defines the ReadCommunity for SNMP v1/v2. Used for the agents that are connecting to the WinCC OA system.

v1WriteCommunity

string

””

-

Defines the WriteCommunity for SNMP v1/v2. Used for the agents that are connecting to the WinCC OA system.

LAProxyPortNr

int

4701

1  -  65535

Specifies the port number of the Live Agent. The Pmon serves as a proxy for the Live agent.

snmpDir

string

"<project_directory>/data"

-

For SNMPv3 the SNMP entity needs a boot counter. This is located in the "snmpv3_boot_counter" file.

Per default the Pmon writes this file into the /data directory from the project directory. If the user has no write access at this directory, so another directory can be set via this config entry.

v1TrapTarget

string

""

-

Specifies the IP address/Port number to which the traps are sent.

e.g. v1TrapTarget  = "192.168.150.29/162"

This entry can be defined as many times as you want to (an own entry for each TrapTarget). All targets that are specified here receive the traps.

restartProjVA

string

"No"

"Yes"|"No"

Project is restarted (in a redundant system) when a value archive manager crashes.

allowSNMPCommands

string

"No"

"Yes"|"No"

Defines whether the MIB entries may be changed via SNMP. See also MIB.

aliveSeconds

int

30

> 0

Within the specified time of seconds the manager that is monitored by the PMON has to increase its alive counter (this means the manager has to give "a sign of life") otherwise the pmon detects this manager as "blocked" and starts an external script (crashAction).

delayStartSeconds

int

0

>= 0

Delays the startup of Pmon for the specified time in seconds. In the time the PMON is waiting for the start, no actions can be carried out in the Console.

restartDelaySeconds

int

0

>= 0

If a manager is re-starting too rapidly, the next start will be delayed by this entered number of seconds. The default value of 0 defines that a manager will no longer be re-started at all. The "crashAction" script is started with the type "DELAYING_RESTART" instead of "NO_RESTART_ANYMORE" when the config entry value is > 0.

Data point

Description

_SNMPManager

The control data point type for the SNMP manager (= SNMP driver). The name of the data point is composed of the driver number and of the name specified in the config file. In standard case it is _1_SNMPManager. The elements of this data point serve for communication with SNMP driver layer and inform about the state of the driver.

Data point

Description

_SNMPLiveAgent

Contains the WinCC OA DPE elements that can be queried via SNMP.

Element

Type

Meaning

Command

string

This element can be set via SNMP. If the MIB object 1.3.6.1.4.1.13828.2.1.12 is described with a text, this text is shown on the DPE. Thus, a CTRL script can connect to this DPE and is activated when the value changes.

Response

string

This element is represented via the MIB object 1.3.6.1.4.1.13828.2.1.13. The above mentioned CTRL script can show a result with the aid of this element. The result is available via SNMP.

SpecificTrap

string

If a value is written and saved in this element, the value is sent as a UserTrap from Live Agent via the PmonProxyAgent to all configured TrapTargets. This only happens when the UserTraps are activated in the config file.

DPTableElements

dyn_string

This element contains the DP elements and their indexes, which can be queried via SNMP.

Element

Type

Meaning

Access.IPAddress

string

The IP address of the entity, e.g. 192.168.1.13, or a computer name, e.g. eiwrk068. If no IP address was set here or it has been deleted (empty string) the entity is disabled automatically and the internal DPE Status.Timeout  is set to FALSE independent of the state it was before.

Access.Timeout

uint

The timeout in 1/100 seconds. This means that a reply to a message has to be sent before this timeout elapses. The default value is 1sec. It might be necessary to increase the timeout in case of slow networks /agents . Valid values are 1 - 10secs.

Access.Retries

uint

Retries before a SNMP protocol error is shown. In case of a timeout, the telegram is repeated. The standard value is 1. Maximum 10 retries can be configured.

Access.Port

uint

The port number used to speak to the agent. The standard SNMP port is 161. You can, however, use an arbitrary port.

Access.SecurityName

string

The SecurityName describes the user/program that requires access to the data.

Access.SecurityLevel

unsigned

The security level describes which security measures should be used for the data exchange.

• noAuthNoPriv  (1) No authentication and no encryption

• authNoPriv (2) Authentication but no encryption

• authPriv (3)Authentication and data encoding

Default value is (1).

Access.AuthProtocol

unsigned

There are two protocols available for the authentication of the SNMP users:

• none (1) no authentication protocol

• HMAC_MD5 (2) MD5 authentication

• HMAC_SHA (3) SHA authentication

Default value is (1).

Access.AuthPasswd

string

The password which is used for authorisation.

Access.PrivProtocol (unsigned)

unsigned

The sent data can also be encrypted in order to increase the security.  For the encryption a protocol has to be selected.

• none (1) no encryption

• DES (2) DES encryption (Data Encryption Standard)

Default is (1).

Access.PrivPasswd

string

The password used for the encryption.

Access.ContextName

string

The addressed context name on the target computer. The context contains specific MIB objects.

Per agent only one context name can be specified. If several context ranges should be queried per agent, several data points have to be created.

Access.ContextEngineID

string

The engine ID of the target computer. If the ID is not specified, it is specified when the data is queried.

Status.ErrorOID

dyn_string

If a protocol error occurs, the corresponding OID is shown using this data point. Since this element is a dynText, all current and not available OIDs are always shown. Furthermore, also the corresponding invalid bits are set for the WinCC OA elements. If an SNMPv3 USM error occur, this will be also written to this DPE.

Status.QueueLength

uint

Shows the current length of the request queue of the agent. This value is only updated when a protocol error occurs. The value should be shown for diagnosis purposes and is irrelevant for the runtime operation.

Status.Timeout

bool

This bit is set when no message was exchanged with the entity for a specific time (configured via the config entry agentConnectTimeout). If no IP address was set in the DPE Access.IPAddress or has been deleted (empty string), this bit iis set to FALSE, independent of its current state.

Notify.ID

unsigned

Last number of OID (Object identifier). This number is appended to the OID notification defined in the WinCC OA MIB. If you modify this DPE a trap is sent to the corresponding SNMP V3 entity by the SNMP manager.

-dbg 26 can be used to get debug information when a trap was sent.

Notify.Text

string

Specify the trap text here. If this element contains a text, the text is sent when Notify.Id is changed.

Browse.Start

string

Defines the start-OID for querying all data of the agent. These will be written to the Browse.Result DPE.

If this DPE is left empty, the query is started with the start-OID "1.3.6.1".

Browse.Result

dyn_string

Contains the result of the query that was started with the Browse.Start DPE. During the browsing the value of this DPE is "1 - started browsing".

Once the browsing is completed, the result contains the data of the agent. One data set always consists of three lines:

1st line: OID

2nd line: Value in a default transformation

3rd line: Data type as number#data type as text

Example with two data sets:

1.3.6.1.2.1.1.1.0

Hardware: x86 Family 6 Model 15 Stepping 8 AT/AT COMPATIBLE

4#OCTETS

1.3.6.1.2.1.1.3.0

0:00:26.60

67#TIMETICKS

Possible values for the data type:

• 2 - INT32

• 3 - BITS

• 4 - OCTETS

• 6 - OID

• 64 - IPADDR

• 65 - CNTR32

• 66 - UINT32

• 67 - TIMETICKS

• 68 - OPAQUE

• 70 - CNTR64

If the result does not contain a number of entries which can be divided by 3, then it is a state message. In this case the first line indicates the status code:

1 - query started

-1 - error

The error code and the description are contained in the second line.

For example:

-1

-5#SNMP++: SNMP request timed out