Change SNMP Attributes (CHGSNMPA)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Change SNMP Attributes (CHGSNMPA) command changes values and options used by the IBM i SNMP agent. The command also is used to specify which SNMP managers receive traps generated by the local system.

The SNMP agent is shipped with the following values for the SNMP attributes.

Keyword: Value
SYSD: *SYSGEN
SYSCONTACT: *NONE
SYSLOC: *NONE
SNDAUTTRP: *YES
AUTOSTART: *NO
OBJACC: *READ
LOGSET: *NO
LOGGET: *NO
LOGTRP: *NO
TRPMGR: *NONE
LCLTRPMGR: *NO for the Start local trap manager element and *NO for the Forward traps element.
ALWSNMPV3: *V3ONLY
DFTTIMEOUT: *DFT
MAXTIMEOUT: *DFT
SNMPENGID: *SYSGEN
SNMPENGB: *DFT
BLKSIZE: 1024 for disk units. For storage pools, the size is determined by the system.
ADLINF: *DFT
STCTIMITV: 30

Restrictions:

You must have input/output system configuration (*IOSYSCFG) special authority to change the SNMP attributes.

Top

Parameters

Keyword	Description	Choices	Notes
SYSD	System description	Character value, SAME, NONE, *SYSGEN	Optional
SYSCONTACT	System contact	Character value, SAME, NONE, *CNTINF	Optional
SYSLOC	System location	Character value, SAME, NONE, *CNTINF	Optional
SNDAUTTRP	Send authentication traps	SAME, YES, *NO	Optional
AUTOSTART	Automatic start	SAME, YES, *NO	Optional
OBJACC	Object access	SAME, READ, WRITE, NONE	Optional
LOGSET	Log set requests	SAME, YES, *NO	Optional
LOGGET	Log get requests	SAME, YES, *NO	Optional
LOGTRP	Log traps	SAME, YES, *NO	Optional
TRPMGR	Trap managers	Single values: SAME, NONE Other values (up to 300 repetitions): Element list	Optional
	Element 1: Manager internet address	Character value
	Element 2: Manager internet address mask	Character value
	Element 3: Community or user name	Character value
	Element 4: Translate community name	YES, NO
	Element 5: Message type	TRAPV1, TRAPV3, *INFORMV3
LCLTRPMGR	Local trap manager	Single values: *SAME Other values: Element list	Optional
	Element 1: Start local trap manager	YES, NO
	Element 2: Forward traps	YES, NO
	Element 3: User name	Character value, *NONE
	Element 4: Inform IP address	Character value, *NONE
ALWSNMPV3	Allow SNMPv3 support	SAME, V3ONLY, YES, NO, *V3AGENT	Optional
DFTTIMEOUT	Default sub-agent timeout	1-3600, SAME, DFT	Optional
MAXTIMEOUT	Maximum sub-agent timeout	1-3600, SAME, DFT	Optional
SNMPENGID	SNMP engine identifier	Character value, SAME, SYSGEN	Optional
SNMPENGB	SNMP engine boots	0-2147483647, SAME, DFT	Optional
BLKSIZE	Block size	Single values: *SAME Other values: Element list	Optional
	Element 1: Storage pool	*DFT, 4K, 8K, 16K, 32K, 64K, 128K, 256K, 512K, 1M, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288, 1048576
	Element 2: Disk unit	*DFT, 1024, 2048, 4096, 8192, 16384, 32768
ADLINF	Additional information	Single values: SAME, DFT Other values (up to 2 repetitions): ASPNBR, SYSD	Optional
STCTIMITV	Statistics time interval	10-3600, SAME, DFT	Optional
ALWDUPID	Allow duplicate identifiers	SAME, YES, *NO	Optional

Top

System description (SYSD)

Specifies a textual description of the IBM i. If the Additional information (ADLINF) parameter of this command specifies *SYSD, the specified text is added to the end of the system generated text. The system description is also known by SNMP managers and agents as sysDescr.

*SAME: The value does not change.
*SYSGEN: The system generated text is returned for the sysDescr value for a get, get-bulk, or get-next request. No additional information is returned when ADLINF(*SYSGEN) is specified.
*NONE: The system generated text is returned for the sysDescr value for a get, get-bulk, or get-next request. No additional information is returned when ADLINF(*SYSGEN) is specified.
system-description: Specify the text that is added to the end of the system generated text returned for the sysDescr value for a get, get-bulk, or get-next request. This text is only added to the system generated text when ADLINF(*SYSD) is also specified. If ADLINF does not specify *SYSD, only the system generated text is returned for the sysDescr value for a get, get-bulk, or get-next request.

Top

System contact (SYSCONTACT)

Specifies the name of the contact person for this IBM i, along with information on how to contact this person. This value is used only by SNMP-specific functions. This value also may be read or modified by an authorized SNMP manager.

*SAME: The value does not change.
*NONE: No system contact exists.
*CNTINF: The value is obtained from the service contact information specified by using the Work with Contact Information (WRKCNTINF) command. The value obtained consists of the contact person and the contact telephone numbers.
system-contact: Specify the name of the contact person and other contact information.

Top

System location (SYSLOC)

Specifies the physical location of this IBM i. This value is used only by SNMP-specific functions. This value also may be read or modified by an authorized SNMP manager.

*SAME: The value does not change.
*NONE: No system location information exists.
*CNTINF: The value is obtained from the service contact information specified by using the Work with Contact Information (WRKCNTINF) command. The value obtained consists of the mailing address.
system-location: Specify the physical location of the system.

Top

Send authentication traps (SNDAUTTRP)

Specifies whether the SNMP agent may send any authenticationFailure traps to any defined SNMP managers. An authenticationFailure trap is sent by the SNMP agent if a request is received from an SNMP manager that contains a community name that is not recognized by the SNMP agent. This trap is only sent when SNDAUTTRP is *YES and when at least one trap manager has been defined. This value may also be read or modified by an authorized SNMP manager.

*SAME: The value does not change.
*YES: authenticationFailure traps may be sent.
*NO: authenticationFailure traps are not sent.

Top

Automatic start (AUTOSTART)

Specifies whether the SNMP agent is started when the STRTCP command or STRTCPSVR SERVER(*AUTOSTART) command runs.

*SAME: The value does not change.
*YES: The SNMP agent is started when the STRTCP command or STRTCPSVR SERVER(*AUTOSTART) command runs.
*NO: The SNMP agent is not started when the STRTCP command runs.

Top

Object access (OBJACC)

Specifies the default object access for SNMP communities.

*SAME: The value does not change.
*READ: Allow SNMP managers that are part of a community to read all management information base (MIB) objects. Modification of MIB objects by SNMP managers is not permitted.
*WRITE: Allow SNMP managers that are part of a community to modify all MIB objects that can be modified. Specifying *WRITE implies *READ access.
*NONE: Do not allow SNMP managers that are part of a community to modify any MIB objects.

Top

Log set requests (LOGSET)

Specifies the default value for whether set requests from SNMP managers are logged in journal QSNMP in library QUSRSYS.

*SAME: The value does not change.
*YES: Set requests are logged.
*NO: Set requests are not logged.

Top

Log get requests (LOGGET)

Specifies the default value for whether get, get-bulk, and get-next requests from SNMP managers are logged in journal QSNMP in library QUSRSYS. The value specified for this paramater also determines whether SNMPv3 engine identifier discovery requests are logged.

*SAME: The value does not change.
*YES: Get, get-bulk, and get-next requests are logged. SNMPv3 engine identifier discovery packets are logged.
*NO: Get, get-bulk, and get-next requests are not logged. SNMPv3 engine identifier discovery packets are not logged.

Top

Log traps (LOGTRP)

Specifies whether trap and inform messages are logged in journal QSNMP in library QUSRSYS.

*SAME: The value does not change.
*YES: Trap and inform messages are logged.
*NO: Trap and inform messages are not logged.

Top

Trap managers (TRPMGR)

Specifies which SNMP managers receive trap and inform messages generated by the IBM i SNMP agent.

*SAME: The value does not change.
*NONE: No trap or inform messages are sent by the IBM i SNMP agent.
Element 1: Manager internet address
manager-internet-address: Specify the internet address of the SNMP manager. The internet address may be an IPv4 or IPv6 address. An IPv4 internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An IPv4 internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address. An IPv6 internet address is specified in the form x:x:x:x:x:x:x:x, where x is a hexadecimal number ranging from 0 through X'FFFF'. "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address. This address is independent of the manager internet address specified on the ADDCOMSNMP and CHGCOMSNMP commands.
Element 2: Manager internet address mask
manager-internet-address-mask: If the associated manager address is an IPv6 address, then the internet address mask is either an IPv6 address mask (for example, FFFF:FFFF::) or an integer from 0 to 128 specifying the number of IPv6 address prefix bits used to construct an IPv6 address mask. If the manager internet address is an IPv4 address, then internet address mask is either an IPv4 address mask (for example, 255.255.255.0) or an integer from 0 to 32 specifying the number of IPv4 address prefix bits used to construct an IPv4 address mask.
Element 3: Community or user name
community-or-user-name: Specify the SNMP community name or SNMP version 3 (SNMPv3) user name to be used when sending a trap or inform message to this SNMP manager. The community name specified does not have to exist on the system. The name may contain characters that cannot be displayed. However, if an SNMPv3 user name is specified, it must exist on the system. Use the Configure TCP/IP SNMP (CFGTCPSNMP) command to add, change, and remove communities or users.
Element 4: Translate community name
*YES: The community or user name is translated to ASCII characters when a trap or inform message is sent to the SNMP manager. This value should be specified when the name consists entirely of characters that can be displayed. An error message is sent if the name cannot be translated to ASCII characters.
*NO: The community name is not translated to ASCII characters when a trap is sent to the SNMP manager. This value should be specified when the community name contains one or more characters that cannot be displayed. This does not apply to an SNMPv3 user name because they are always translated to ASCII.
Element 5: Message type
*TRAPV1: An SNMPv1 trap message is sent to the SNMP manager.
*TRAPV3: An SNMPv3 trap message is sent to the SNMP manager.
*INFORMV3: An SNMPv3 inform message is sent to the SNMP manager.

Top

Local trap manager (LCLTRPMGR)

Specifies which SNMP managers receive trap and inform messages generated by the IBM i SNMP agent.

*SAME: The value does not change.
Element 1: Start local trap manager
*NO: The local trap manager is not started when the SNMP server is started. The Start Trap Manager (STRTRPMGR) command must be used to start the local trap manager. The local trap manager is not ended when the SNMP server is ended. The End Trap Manager (ENDTRPMGR) command must be used to end the local trap manager.
*YES: The local trap manager is started when the SNMP server is started and ended when the SNMP server is ended.
Element 2: Forward traps
*NO: The local trap manager does not forward any trap or inform messages that it receives.
*YES: The local trap manager forwards trap and inform messages that it receives. If an SNMPv1 trap is received, the trap will be forwarded to all trap managers that are configured to receive SNMPv1 traps (TRPMGR parameter). If an SNMPv3 trap is received, the trap will be forwarded to all trap managers that are configured to receive SNMPv3 traps (TRPMGR parameter). If an inform message is received, the inform message will only be forwarded to the inform manager specified by the Inform IP address and User name elements of this parameter. In addition, SNMPv3 trap and inform messages will only be forwarded if the configured SNMPv3 user specifies at least the same authority level as the message that was received.
Element 3: User name
*NONE: An SNMPv3 user is not specified. Inform messages will not be forwarded.
User-name-for-inform: Specify the SNMPv3 user name to used for forwarding inform messages. The specified user must exist on the system in order to send the inform message, and it must specify at least the same authority level as the inform message that was received.
Element 4: Inform IP address
*NONE: An IP address for inform messages is not specified. Inform messages will not be forwarded.
IP-address-for-inform: Specify the internet address of the SNMP manager. The internet address may be an IPv4 or IPv6 address. An IPv4 internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An IPv4 internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address. An IPv6 internet address is specified in the form x:x:x:x:x:x:x:x, where x is a hexadecimal number ranging from 0 through X'FFFF'. "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address.

Top

Allow SNMPv3 support (ALWSNMPV3)

Specifies if SNMP version 3 (SNMPv3) support is enabled. The primary goal of SNMPv3 is to define a secure version of the SNMP by protecting the system from common threats such as modification of information, masquerade, disclosure, and message stream modification. SNMPv3 allows the configuration of SNMP users. In order to configure the list of SNMP users, the CFGTCPSNMP option 3 command can be used. End of change

*SAME: The value does not change.
*V3ONLY: Only SNMPv3 messages are supported. SNMPv1 messages will be rejected. SNMPv1 traps will not be sent. The use of SNMPv1 manager APIs is not allowed. The SNNP trap manager will not receive SNMPv1 traps.
*V3AGENT: Only SNMPv3 messages are supported by the IBM i agent. SNMPv1 messages will be rejected. SNMPv1 traps will not be sent by the agent. The use of SNMPv1 manager APIs is allowed. The SNMP trap manager will receive and log SNMPv1 traps.
*YES: SNMPv3 support is enabled. Both SNMPv1 and SNMPv3 messages are allowed. Both SNMPv1 and SNMPv3 trap and inform messages may be sent. The use of both SNMPv1 and SNMPv3 manager APIs is allowed.
*NO: SNMPv3 support is not enabled. SNMPv3 messages will be rejected. No SNMPv3 trap or inform messages will be sent. The use of SNMPv3 manager APIs is not allowed.

Top

Default sub-agent timeout (DFTTIMEOUT)

Specifies the default timeout (in seconds) that this agent waits for a response from a Subagent. This value is used if a timeout value is not specified for the subtree nor for the subagent that exports.

*SAME: The value does not change.
*DFT: The default timeout value of 5 seconds is used.
1-3600: Specify the number of seconds to be used for the default sub-agent timeout value. NOTEThis value should be equal or less than the value specified for MAXTIMEOUT.

Top

Maximum sub-agent timeout (MAXTIMEOUT)

Specifies the maximum timeout (in seconds) that this agent allows for timeout values for Sub-agents. When you try to set any other timeout value it must be between 1 and this maximum value.

*SAME: The value does not change.
*DFT: The default timeout value of 60 seconds is used.
1-3600: Specify the number of seconds to be used for the maximum sub-agent timeout value.

Top

SNMP engine identifier (SNMPENGID)

Uniquely identifies the agent within an administrative domain. By default, the engine identifier is created using a vendor-specific formula and incorporates the IP address of the agent. However, any engine identifier that is consistent with the snmpEngineID definition in RFC 3411 and that is also unique within the administrative domain can be specified.

*SAME: The value does not change.
*SYSGEN: The engine identifier is generated by the IBM i SNMP agent.
engine-identifier: Specify the engine identifier to be be used for the IBM i SNMP agent.

Top

SNMP engine boots (SNMPENGB)

Specifies the number of times the agent has been restarted since the SNMP engine identifier was last changed.

*SAME: The value does not change.
*DFT: The default value of 0 is used.
0-2147483647: Specify the number of times the IBM i SNMP agent has been restarted since the last change of the engine identifier. Note that a value of 2147483647 is used to indicate that the SNMP agent was unable to determine its latest SNMP engine boots value or that it has reached the maximum number of boots. In order for the SNMP server to start, this value should be set to a value different from 2147483647 either by reseting the value of the SNMP engine boots or by changing the SNMP engine identifier.

Top

Block size (BLKSIZE)

Specifies the block size that will be used when returning information in the hardware resources Management Information Base (MIB). Specifying a block size that is too small can have unpredictable results when retrieving the size of large storage pools or disk units since the size is returned as the number of blocks instead of the number of bytes. Changes to this parameter will take effect the next time the SNMP server starts.

Single values

*SAME: The value does not change.

Element 1: Storage pool

*DFT: The default value is determined by the system.
4K (4096), 8K (8192), 16K (16384), 32K (32768), 64K (65536), 128K (131072), 256K (262144), 512K (524288), 1M (1048576): Specify the block size to be used when retrieving storage pool information. Either the special value or the equivalent numerical value may be specified. Changing this value affects information retrieved for both auxiliary storage pools and memory pools.

Element 2: Disk unit

*DFT: The default value of 1024 is used.
1024, 2048, 4096, 8192, 16384, 32768: Specify the block size to be used when retrieving disk unit information. Using a disk unit block size larger than 1024 causes the disk unit capacity information to no longer be compliant with RFC 1514, however, it can be changed to avoid issues with SNMP Managers receiving negative capacity values for high capacity disk units.

Top

Additional information (ADLINF)

Specifies whether information in addition to the default system generated information is returned for selected SNMP object identifiers.

Single values

*SAME: The value does not change.
*DFT: Default system generated information is returned for all get, get-bulk, and get-next requests.

Other values

*SYSD: The text specified by the System description (SYSD) parameter of this command is added to the end of the default system generated text when returning the value of the system description. The system description is also known by SNMP managers and agents as sysDescr.
*ASPNBR: The number assigned to the storage pool is added to the end of the storage pool description text when returning the value of the storage pool description. The storage pool description is also known by SNMP managers and agents as hrStorageDescr.

Top

Statistics time interval (STCTIMITV)

Specifies the default time interval used to gather statistical data.

*SAME: The value does not change.
*DFT: The default time interval of 30 seconds is used.
10-3600: Specify the number of seconds to be used for the statistics time interval.

Top

Allow duplicate identifiers (ALWDUPID)

This parameter is not used by SNMP and will be removed at a future time.

Top

Examples

Example 1: Changing System Description, System Contact and Automatic Start

CHGSNMPA SYSD('Software Test System')
         SYSCONTACT('Jane Doe, Phone 555-1212') AUTOSTART(*YES)
         ADLINF(*SYSD)

This command changes the system description and system contact information. It specifies that the SNMP agent should start when the STRTCP command runs. It specifies that additional information will be returned by the IBM i SNMP agent when an SNMP manager requests the system description (sysDescr). The sysDescr value returned will consist of the default system generated text followed by the text "Software Test System." All other values are unchanged.

Example 2: Changing Trap Managers

CHGSNMPA   TRPMGR(('9.8.7.6' '255.255.0.0' 'v3User' *YES *TRAPV3)
                  ('2001:db8::10f' 64 'v3User2' *YES *TRAPV3))

This command causes any traps generated by the local system to be sent to SNMP managers that have internet protocol addresses 9.8.7.6 and 2001:db8::10f. The SNMPv3 user v3User is used for traps sent to 9.8.7.6. The SNMPv3 user v3User2 is used for traps sent to 2001:db8::10f. End of change

Example 3: Enabling SNMPv3, changing the Default and Maximum Sub-agent Timeout, regenerating the SNMP engine ID and resetting the SNMP engine boots value End of change

CHGSNMPA   ALWSNMPV3(*YES) DFTTIMEOUT(10) MAXTIMEOUT(3600)
SNMPENGID(*SYSGEN) SNMPENGB(0) LOGGET(*YES)

This command allows SNMPv3 to be enabled in the system and changes the default sub-agent timeout to 10 and the maximum sub-agent timeout to 3600. This command causes the IBM i agent to generate the SNMP engine and resets the SNMP engine boots count. Get, get-bulk , get-next, and SNMPv3 engine identifier discovery requests are logged by default to journal QSNMP in library QUSRSYS unless specified otherwise by the specific community or SNMPv3 user. All other values are unchanged. End of change

Example 4: Configuring the Local Trap Manager

CHGSNMPA LCLTRPMGR(*YES *YES '10.1.2.3' 'v3User')

This command configures the IBM i local trap manager to start when SNMP starts. The local trap manager will also forward trap and inform messages. If an SNMPv3 inform message is received, it will forward it to the trap manager application at IP address 10.1.2.3. The SNMPv3 user v3User will be used for sending the inform message to IP address 10.1.2.3.

Top

Error messages

*ESCAPE Messages

TCP4001: Error occurred accessing SNMP configuration information.
TCP8050: *IOSYSCFG authority required to use &1.

Top

Change SNMP Attributes (CHGSNMPA)

Restrictions:

Parameters

System description (SYSD)

System contact (SYSCONTACT)

System location (SYSLOC)

Send authentication traps (SNDAUTTRP)

Automatic start (AUTOSTART)

Object access (OBJACC)

Log set requests (LOGSET)

Log get requests (LOGGET)

Log traps (LOGTRP)

Trap managers (TRPMGR)

Element 1: Manager internet address

Element 2: Manager internet address mask

Element 3: Community or user name

Element 4: Translate community name

Element 5: Message type

Local trap manager (LCLTRPMGR)

Element 1: Start local trap manager

Element 2: Forward traps

Element 3: User name

Element 4: Inform IP address

Allow SNMPv3 support (ALWSNMPV3)

Default sub-agent timeout (DFTTIMEOUT)

Maximum sub-agent timeout (MAXTIMEOUT)

SNMP engine identifier (SNMPENGID)

SNMP engine boots (SNMPENGB)

Block size (BLKSIZE)

Single values

Element 1: Storage pool

Element 2: Disk unit

Additional information (ADLINF)

Single values

Other values

Statistics time interval (STCTIMITV)

Allow duplicate identifiers (ALWDUPID)

Examples

Example 1: Changing System Description, System Contact and Automatic Start

Example 2: Changing Trap Managers

Example 4: Configuring the Local Trap Manager

Error messages