PISNMP interface page

Since the startup file of the PI SNMP interface is maintained automatically by the PI ICU, use the Pisnmp page to configure the startup parameters and do not make changes in the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters.

The PI SNMP ICU Control for PI ICU has two sections. A yellow text box indicates that an invalid value has been entered, or that a required value has not been entered.

On the General Configuration tab, in the Device Authentication Configuration box, there are two checkboxes:

• When you check the Read and encrypt authentication info from pisnmp#.pwd instead of Exdesc box, the interface will use the password file (pisnmp#.pwd) as the source of authentication and data security information.

  Note: # in the password filename is the interface service ID.

  Checking this box is equivalent to specifying -pwd in the startup command file.

  Tip: OSIsoft recommends checking the box as a security best practice for authentication and data security settings. If you do not check the Read and encrypt authentication info from pisnmp#.pwd instead of Exdesc box, then the interface will look for authentication information in each point's Extended Descriptor.

• When you check the Delete plain text password file after encryption (start of interface) box, the interface will store authentication and data security configuration information in the Windows Credential Manager and delete password files when the interface starts. Checking this box is equivalent to specifying -enc in the startup command file.

  Tip: OSIsoft recommends checking the box as a security best practice for authentication and data security settings.

The password file, pisnmp#.pwd, is a plain text file. Use the ICU control to invoke the Notepad editor by clicking the Edit button in the Password File on the General Configuration of the PI SNMP ICU Control to create or modify the password file. By using the ICU control to create and/or edit the password file, then the file security will be updated to allow the interface service with correct privileges for access to the file. The format of the password file is described in the Authentication and data security topic earlier in this user guide; it is restated below for your convenience:

• For SNMPv1 and SNMPv2c authentication you must specify the correct SNMP community string:

  • For input points use the keyword CS=community string. For example: CS=public;

  • For output points use keyword WCS=community string. For example: WCS=private;

  • You should put the community string in the password file.

  • You should also use the command line parameter -ENC, which will cause the interface to store the information in Windows Credential Manager and to delete password files when the interface starts.

  • You should configure a separate instance of the interface for output points. This will help isolate that feature to the minimal set of tags that need output support, and then use the read only version of the interface for the input points.

• SNMPv3 authentication employs a user-based security model and supports secure signing and encryption of messages (data). You must specify the user name and password. Authentication and data security configuration should be placed in the password file. At startup of the interface, information in the password file will be stored in the Windows Credential Manger. You should also use the -ENC command line parameter, which will cause the interface to delete the password file after having stored the information in the Windows Credential Manager. On restart of the interface, the information will then be read from the Windows Credential Manager.

  • For the user name use the keyword USER=username. For example: USER=manager;

  • For the password, use the keyword APW=password. For example: APW=mgrpwd;

  • For authentication, use the keyword AUTH=authentication type. The supported authentication types are MD5 and SHA. For example: AUTH=MD5;

    Note: Consult the documentation for the SNMP device to determine which to use. If you omit this setting the interface defaults to MD5.

  • For contextName use the keyword CONTEXT=contextName.

• If multiple community strings (SNMPv1 and SNMPv2c) or multiple User\Password (SNMPv3) exist for the same host, use the optional keyword CG=credential group to distinguish them. In other words, the combination of a host and a credential group definitions must be unique.

• For security best practices, if the SNMPv3 agent supports a privacy type then we recommend configuring the privacy key and privacy type:

  Note: Encryption is performed by using a privacy key to encrypt the data portion of the message being sent, and the privacy type (protocol) can be either AES or DES.

  • For the privacy key use the keyword PPW=password. For example: PPW=mypassword;

  • For the privacy type use the keyword PRIV=privacy type where privacy type can be DES or AES. The interface defaults to DES if not specified. For example: PRIV=AES;

Tips

• If you specify USER with no password, you will have an unauthenticated connection and data will be unencrypted.

• If you specify USER and APW, you will have an authenticated connection but data will be unencrypted.

• If you specify USER, APW and PPW, you will have an authentication connection and data will be encrypted.

• If you specify USER, APW, PPW, and PRIV, you will have an authenticated connection and data will be encrypted using either AES or DES. OSIsoft recommends that you specify AES. This configuration is the most secure configuration of the available options.

The following is an example pisnmp#.pwd for an SNMPv1 or SNMPv2c agent:

host=device_name; user comments
V=2c;
CS=community_string; read community string of previous entry

The following is a template for a pisnmp#.pwd file for an SNMPv3 agent:

host=device_name; user comments
V=3;
USER=username; SNMPv3 username
AUTH=MD5; Authentication protocol. Can be MD5 or SHA
APW=password; Authentication password
PPW=password; Privacy password

The following is an example pisnmp#.pwd file for several SNMPv2c and SNMPv3 agents:

host=router1; router1 is our main router
V=2c;
CS=public; read community string for <router1>
host=192.168.100.10
V=2c;
CS=company123; read community string for <192.168.100.10>
host=switch2;
V=2c;
CS=gnomes11; read community string for <switch2>
host=router3;
V=3;
USER=manager; SNMPv3 user for <router3>
AUTH=SHA; Use SHA authentication
APW=23oaktree; authentication password for <router3>
PPW=hummingbird; privacy password for <router3>
CONTEXT=contextName;

The following is an example of a pisnmp#.pwd file when multiple users exist for the same host (SNMPv3):

host=host1;
CG=1; credential group one
V=3;
USER=user1;
APW=apwd1;
PPW=ppwd1;
CONTEXT=context1;
host=host1;
CG=2; credential group two
V=3;
USER=user2;
APW=apwd2;
PPW=ppwd2;
CONTEXT=context2;

Note: A single HOST entry does not apply to the tags, the HOST entry in the file is not used by the interface as far as the tag definition HOST.

Note that blank lines are allowed only at the end of the file. Also, only one community string or username can be specified for a particular host. If multiple community strings or usernames are needed to access different data on the same SNMP agent, either a separate copy of the interface must be run, or separate aliases for the SNMP device in the interface node's host file must be created. An entry then must be created in pisnmp#.pwd for each alias. (-PWD)

Note: The content of this .pwd file is case sensitive.

• Number of GetRequest retries

  The number in this text box specifies the number of times PI SNMP retries its transmission of an SNMP GetRequest message to the network device. The default number of retries is 3. This setting is equivalent to the -retries= parameter in the startup file. (-RETRIES=#)

• Number of tags per set

  The number in this text box specifies the number of tags per set. When Location3=1, PI SNMP groups tags into a set in order to get multiple OID values for a single SNMP GetRequest message. The default number of tags per set is 5. This setting is equivalent to the -setcount= parameter in the startup file. (-SETCOUNT=#)

• SNMP port number

  This is the port number that the interface uses to communicate with the SNMP enabled device. The default is 161. This setting is equivalent to the -port= parameter in the startup file. (-PORT=#)

• Timeout duration (msec)

  The number in this text box specifies the number of milliseconds that PI SNMP will wait for a reply from the network device. The default timeout is 3000 milliseconds. If PI SNMP does not get a reply after the specified number of retries and timeouts, it writes I/O Timeout to the point(s) for that particular scan. This setting is equivalent to the -timeout= parameter in the startup file. (-TIMEOUT=#)

• Consecutive timeouts

  The number in this text box specifies the consecutive number of timeouts threshold for a device to be considered inaccessible. If PI SNMP exceeds this value when it attempts to poll a particular device, and the scan period has elapsed, then the polling of the device terminates. PI SNMP writes I/O Timeout to the remaining tags specific to the device. If the scan period has not elapsed, then PI SNMP will continue its attempt to process the tags for the device until the scan period has elapsed. This setting is equivalent to the -cto= parameter in the startup file. The default value is 3. (-cto=#)

• Write "Configure" to rejected points

  Checking this box tells the interface to write Configure to rejected points. This setting is equivalent to the -cr parameter in the startup file. (-CR=#)

• Allow SNMP SETs/PI outputs

  To have the interface to support SNMP SETs/PI outputs, check this box. (-OUT)

• Additional parameters

  This section is provided for any additional parameters that the current ICU Control does not support.

  

• Get data from one device

  Checking this box allows the interface to retrieve data from a single device using either the TCP/IP address of the device or the hostname. This setting is equivalent to the -device= parameter in the startup file.

• IP Address

  These four text boxes allow entry of a TCP/IP address for the single device configuration. The values must be a number between 1 and 255 for each text box. (-DEVICE=###.###.###.###)

• Hostname

  This box is used to enter the host name for the single device configuration. (-DEVICE=<Hostname>)

  Note: The UniInt Interface User Manual includes details about other command-line parameters, which may be useful.