- java.lang.Object
-
- org.snmp4j.SNMP4JSettings
-
public final class SNMP4JSettings extends java.lang.Object
TheSNMP4JSettings
class implements a central configuration class of the SNMP4J framework. As a rule of thumb, changes to the default configuration should be made before any other classes of the SNMP4J API are instantiated or referenced by the application code.- Since:
- 1.5
- Version:
- 3.6.1
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SNMP4JSettings.ReportSecurityLevelStrategy
Specifies the how the security level of retry requests after a REPORT PDU is set.static class
SNMP4JSettings.Snmp4jStatistics
-
Field Summary
Fields Modifier and Type Field Description static int
AGENTPP_ENTERPRISE_ID
The enterprise ID of AGENT++ which is the root OID also for SNMP4J.private static boolean
allowSNMPv2InV1
This setting can used to be compatible with some faulty SNMP implementations which send Counter64 objects with SNMPv1 PDUs.private static boolean
checkUsmUserPassphraseLength
The checkUsmUserPassphraseLength specifies whether the minimum USM pasaphrase length should be checked when creating UsmUser instances (RFC3414 §11.2).private static java.lang.Character
defaultNonPrintableEscapeCharacter
Default escape character forVariable
s to avoid non-printable characters in theirVariable.toString()
output.private static int
defaultRetries
Default number of retries for packet oriented transport protocols (i.e.private static long
defaultTimeoutMillis
Default timeout in milliseconds for SNMP communication (Command Request <<->> Response) is 1000 milliseconds.private static int
enterpriseID
The enterprise ID that is used to build SNMP engine IDs and other enterprise specific OIDs.private static boolean
extensibilityEnabled
Specifies whether SNMP4J can be extended by own implementation of security protocols, transport mappings, address types, SMI syntaxes, etc.private static boolean
forwardRuntimeExceptions
By default SNMP4J (and SNMP4J-Agent*) catch runtime exceptions at thread boundaries of API controlled threads.private static int
maxEngineIdCacheSize
By default allow worth of ~2MB memory for engine ID cache.private static int
maxSizeRequestPDU
Default maximum size of request PDUs.private static boolean
noGetBulk
Suppress GETBULK sending.private static OIDTextFormat
oidTextFormat
By default SNMP4J uses theSimpleOIDTextFormat
to convertOID
s to/from a textual representation.private static SNMP4JSettings.ReportSecurityLevelStrategy
reportSecurityLevelStrategy
This flag enables/disables (default) whether REPORT PDUs should be send by a command responder with securityLevelSecurityLevel.noAuthNoPriv
if otherwise the command generator would not able to receive thePDU.REPORT
.private static java.lang.Boolean
secretLoggingEnabled
private static SNMP4JSettings.Snmp4jStatistics
snmp4jStatistics
The snmp4jStatistics value defines the level of statistic values that are collected in extension to those collected for the SNMP standard.private static ThreadFactory
threadFactory
By default SNMP4J usesThread
instances to run concurrent tasks.private static long
threadJoinTimeout
The default Thread join timeout, used for example by theDefaultThreadFactory
, defines the maximum time to wait for a Thread running a worker task to end that task (end join the main thread if that Thread has been exclusively used for that task).private static TimerFactory
timerFactory
By default SNMP4J usesTimer
instances to run timed tasks.private static VariableTextFormat
variableTextFormat
By default SNMP4J uses theSimpleVariableTextFormat
to convertVariableBinding
s to/from a textual representation.
-
Constructor Summary
Constructors Constructor Description SNMP4JSettings()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.lang.Character
getDefaultNonPrintableEscapeCharacter()
Gets the default non-printable character escape character.static int
getDefaultRetries()
Get the default number of retries for packet oriented transport mappings.static long
getDefaultTimeoutMillis()
Get the default timeout forAbstractTarget
.static int
getEnterpriseID()
Gets the enterprise OID used for creating SNMP engine IDs and other enterprise specific identifiers.static int
getMaxEngineIdCacheSize()
Gets the maximum number of engine IDs to be hold in the cache of theMPv3
.static int
getMaxSizeRequestPDU()
static OIDTextFormat
getOIDTextFormat()
Gets the OID text format for textual representation of OIDs.static SNMP4JSettings.ReportSecurityLevelStrategy
getReportSecurityLevelStrategy()
static SNMP4JSettings.Snmp4jStatistics
getSnmp4jStatistics()
Get the SNMP4J statistics level.static ThreadFactory
getThreadFactory()
Gets the thread factory.static long
getThreadJoinTimeout()
Gets the Thread join timeout used to join threads if no explicit timeout is set.static TimerFactory
getTimerFactory()
Gets the timer factory.static VariableTextFormat
getVariableTextFormat()
Gets the variable text format for textual representation of variable bindings.static boolean
isAllowSNMPv2InV1()
static boolean
isCheckUsmUserPassphraseLength()
static boolean
isExtensibilityEnabled()
Tests if the extensibility feature is enabled.static boolean
isForwardRuntimeExceptions()
Indicates whether runtime exceptions should be thrown on thread boundaries controlled by SNMP4J and related APIs.static boolean
isNoGetBulk()
static java.lang.Boolean
isSecretLoggingEnabled()
Check if logging secrets with their secret value in any debug level is allowed (true
) or not (false
).static void
setAllowSNMPv2InV1(boolean allowSNMPv2InV1)
Sets the compatibility flag for Counter64 usage in SNMPv1 PDUs and the ability to decode SNMPv2 traps in SNMPv1 version PDUs.static void
setCheckUsmUserPassphraseLength(boolean checkUsmUserPassphraseLength)
static void
setDefaultNonPrintableEscapeCharacter(java.lang.Character defaultNonPrintableEscapeCharacter)
Gets the default non-printable character escape character.static void
setDefaultRetries(int defaultRetries)
Set the default number of retries for packet oriented transport mappings, default is 0.static void
setDefaultTimeoutMillis(long defaultTimeoutMillis)
Set the default timeout forAbstractTarget
.static void
setEnterpriseID(int enterpriseID)
Sets the enterprise OID used for creating SNMP engine IDs and other enterprise specific identifiers.static void
setExtensibilityEnabled(boolean enable)
Enables (or disables) the extensibility feature of SNMP4J.static void
setForwardRuntimeExceptions(boolean forwardExceptions)
Enables or disables runtime exception forwarding.static void
setMaxEngineIdCacheSize(int maxEngineIdCacheSize)
Sets the maximum number of engine IDs that can be cached by theMPv3
.static void
setMaxSizeRequestPDU(int maxSizeRequestPDU)
Sets the maximum size of a request PDU.static void
setNoGetBulk(boolean noGetBulk)
static void
setOIDTextFormat(OIDTextFormat newOidTextFormat)
Sets the OID text format to be used by SNMP4J.static void
setReportSecurityLevelStrategy(SNMP4JSettings.ReportSecurityLevelStrategy reportSecurityLevelStrategy)
static boolean
setSecretLoggingEnabled(boolean enableSecretLogging)
Activates or deactivates the secret logging.static void
setSnmp4jStatistics(SNMP4JSettings.Snmp4jStatistics snmp4jStatistics)
Sets the SNMP4J statistics level.static void
setThreadFactory(ThreadFactory newThreadFactory)
Sets the thread factory for creating new threads of execution.static void
setThreadJoinTimeout(long millis)
Sets the Thread join timeout used to join threads if no explicit timeout is set.static void
setTimerFactory(TimerFactory newTimerFactory)
Sets the timer factory for creating new timer instances.static void
setVariableTextFormat(VariableTextFormat newVariableTextFormat)
Sets the variable text format to be used by SNMP4J.
-
-
-
Field Detail
-
AGENTPP_ENTERPRISE_ID
public static final int AGENTPP_ENTERPRISE_ID
The enterprise ID of AGENT++ which is the root OID also for SNMP4J.- See Also:
- Constant Field Values
-
maxEngineIdCacheSize
private static int maxEngineIdCacheSize
By default allow worth of ~2MB memory for engine ID cache.
-
extensibilityEnabled
private static boolean extensibilityEnabled
Specifies whether SNMP4J can be extended by own implementation of security protocols, transport mappings, address types, SMI syntaxes, etc. through property files defined via System properties. If set tofalse
all classes SNMP4J is aware of will be used hard coded which speeds up initialization and is required to use SNMP4J in a secure environment where System properties are not available (i.e. in an unsigned applet).- Since:
- 1.2.2
-
forwardRuntimeExceptions
private static volatile boolean forwardRuntimeExceptions
By default SNMP4J (and SNMP4J-Agent*) catch runtime exceptions at thread boundaries of API controlled threads. In SNMP4J such a thread runs in eachTransportMapping
and in eachSnmp
session object. To ensure robust runtime behavior, unexpected runtime exceptions are caught and logged. If you need to localize and debug such exceptions then set this value totrue
.- Since:
- 1.8.1
-
threadFactory
private static ThreadFactory threadFactory
By default SNMP4J usesThread
instances to run concurrent tasks. For environments with restricted thread management like Java EE application servers, a custom thread factory can be used.- Since:
- 1.9
-
timerFactory
private static TimerFactory timerFactory
By default SNMP4J usesTimer
instances to run timed tasks. For environments with restricted thread management like Java EE application servers, a custom timer factory can be used.- Since:
- 1.9
-
oidTextFormat
private static OIDTextFormat oidTextFormat
By default SNMP4J uses theSimpleOIDTextFormat
to convertOID
s to/from a textual representation.- Since:
- 1.10
-
variableTextFormat
private static VariableTextFormat variableTextFormat
By default SNMP4J uses theSimpleVariableTextFormat
to convertVariableBinding
s to/from a textual representation.- Since:
- 1.10
-
threadJoinTimeout
private static long threadJoinTimeout
The default Thread join timeout, used for example by theDefaultThreadFactory
, defines the maximum time to wait for a Thread running a worker task to end that task (end join the main thread if that Thread has been exclusively used for that task). The default value is 60 seconds (1 min.).
-
allowSNMPv2InV1
private static boolean allowSNMPv2InV1
This setting can used to be compatible with some faulty SNMP implementations which send Counter64 objects with SNMPv1 PDUs.
-
noGetBulk
private static boolean noGetBulk
Suppress GETBULK sending. Instead use GETNEXT. This option may be useful in environments with buggy devices which support SNMPv2c or v3 but do not support the mandatory GETBULK PDU type.
-
reportSecurityLevelStrategy
private static SNMP4JSettings.ReportSecurityLevelStrategy reportSecurityLevelStrategy
This flag enables/disables (default) whether REPORT PDUs should be send by a command responder with securityLevelSecurityLevel.noAuthNoPriv
if otherwise the command generator would not able to receive thePDU.REPORT
. RFC 3412 §7.6.2.3 requires that the securityLevel is the same as in the confirmed class PDU if not explicitly otherwise specified. ForSnmpConstants.usmStatsUnsupportedSecLevels
reports, this would always render the command responder unable to return the report. Setting this flag toSNMP4JSettings.ReportSecurityLevelStrategy.noAuthNoPrivIfNeeded
reactivates the behavior of SNMP4J prior to v2.2 which sends out the reports withSecurityLevel.noAuthNoPriv
if otherwise, the report would not be sent out.- Since:
- 2.2
-
enterpriseID
private static int enterpriseID
The enterprise ID that is used to build SNMP engine IDs and other enterprise specific OIDs. This value should be changed by API users from other enterprises (companies or organizations).- Since:
- 2.2.4
-
snmp4jStatistics
private static SNMP4JSettings.Snmp4jStatistics snmp4jStatistics
The snmp4jStatistics value defines the level of statistic values that are collected in extension to those collected for the SNMP standard.- Since:
- 2.4.2
-
checkUsmUserPassphraseLength
private static boolean checkUsmUserPassphraseLength
The checkUsmUserPassphraseLength specifies whether the minimum USM pasaphrase length should be checked when creating UsmUser instances (RFC3414 §11.2). Default is yes.- Since:
- 2.5.0
-
defaultTimeoutMillis
private static long defaultTimeoutMillis
Default timeout in milliseconds for SNMP communication (Command Request <<->> Response) is 1000 milliseconds.- Since:
- 3.5.0
-
defaultRetries
private static int defaultRetries
Default number of retries for packet oriented transport protocols (i.e. UDP and DTLS) is no retry (0).- Since:
- 3.5.0
-
maxSizeRequestPDU
private static int maxSizeRequestPDU
Default maximum size of request PDUs. Although this value is typically configured onTarget
s individually, it sometimes makes sense to configure this value to less than the maximum value of 65535 (which is the default).- Since:
- 3.5.0
-
defaultNonPrintableEscapeCharacter
private static java.lang.Character defaultNonPrintableEscapeCharacter
Default escape character forVariable
s to avoid non-printable characters in theirVariable.toString()
output.- Since:
- 3.6.1
-
secretLoggingEnabled
private static java.lang.Boolean secretLoggingEnabled
-
-
Method Detail
-
getMaxSizeRequestPDU
public static int getMaxSizeRequestPDU()
-
setMaxSizeRequestPDU
public static void setMaxSizeRequestPDU(int maxSizeRequestPDU)
Sets the maximum size of a request PDU. This value must be betweenSnmpConstants.MIN_PDU_LENGTH
and 65536 bytes (including).- Parameters:
maxSizeRequestPDU
- a value greater or equal to 494 and less or equal to 65535.- Since:
- 3.5.0
-
getDefaultRetries
public static int getDefaultRetries()
Get the default number of retries for packet oriented transport mappings.- Returns:
- the default number of retries, should be greater than or equal to zero.
- Since:
- 3.5.0
-
setDefaultRetries
public static void setDefaultRetries(int defaultRetries)
Set the default number of retries for packet oriented transport mappings, default is 0.- Parameters:
defaultRetries
- the number maximum of retries before a request is timed out. Must be greater than or equal to zero.
-
setExtensibilityEnabled
public static void setExtensibilityEnabled(boolean enable)
Enables (or disables) the extensibility feature of SNMP4J. When enabled, SNMP4J checks certain properties files that describe which transport mappings, address types, SMI syntaxes, security protocols, etc. should be supported by SNMP4J.By default, the extensibility feature is disabled which provides a faster startup and since no system properties are read, it ensures that SNMP4J can be used also in secure environments like applets.
- Parameters:
enable
- iftrue
activates extensibility or iffalse
disables it. In the latter case, SNMP4J's default configuration will be used with all available features.- Since:
- 1.2.2
-
isExtensibilityEnabled
public static boolean isExtensibilityEnabled()
Tests if the extensibility feature is enabled.- Returns:
- if
true
the extensibility is enabled otherwise it is disabled. In the latter case, SNMP4J's default configuration will be used with all available features. - Since:
- 1.2.2
-
setForwardRuntimeExceptions
public static void setForwardRuntimeExceptions(boolean forwardExceptions)
Enables or disables runtime exception forwarding.- Parameters:
forwardExceptions
-true
runtime exceptions are thrown on thread boundaries controlled by SNMP4J and related APIs. Default isfalse
.- Since:
- 1.8.1
- See Also:
forwardRuntimeExceptions
-
isForwardRuntimeExceptions
public static boolean isForwardRuntimeExceptions()
Indicates whether runtime exceptions should be thrown on thread boundaries controlled by SNMP4J and related APIs.- Returns:
true
runtime exceptions are thrown on thread boundaries controlled by SNMP4J and related APIs. Default isfalse
.- Since:
- 1.8.1
-
getThreadFactory
public static ThreadFactory getThreadFactory()
Gets the thread factory.- Returns:
- a ThreadFactory.
- Since:
- 1.9
-
setThreadFactory
public static void setThreadFactory(ThreadFactory newThreadFactory)
Sets the thread factory for creating new threads of execution.- Parameters:
newThreadFactory
- a ThreadFactory (must not benull
).- Since:
- 1.9
-
getTimerFactory
public static TimerFactory getTimerFactory()
Gets the timer factory.- Returns:
- a TimerFactory.
- Since:
- 1.9
-
setTimerFactory
public static void setTimerFactory(TimerFactory newTimerFactory)
Sets the timer factory for creating new timer instances.- Parameters:
newTimerFactory
- a TimerFactory (must not benull
).- Since:
- 1.9
-
getOIDTextFormat
public static OIDTextFormat getOIDTextFormat()
Gets the OID text format for textual representation of OIDs.- Returns:
- an
OIDTextFormat
instance. - Since:
- 1.10
-
setOIDTextFormat
public static void setOIDTextFormat(OIDTextFormat newOidTextFormat)
Sets the OID text format to be used by SNMP4J.- Parameters:
newOidTextFormat
- the newOIDTextFormat
(must not benull
).- Since:
- 1.10
-
getVariableTextFormat
public static VariableTextFormat getVariableTextFormat()
Gets the variable text format for textual representation of variable bindings.- Returns:
- an
VariableTextFormat
instance. - Since:
- 1.10
-
setVariableTextFormat
public static void setVariableTextFormat(VariableTextFormat newVariableTextFormat)
Sets the variable text format to be used by SNMP4J.- Parameters:
newVariableTextFormat
- the newVariableTextFormat
(must not benull
).- Since:
- 1.10
-
getThreadJoinTimeout
public static long getThreadJoinTimeout()
Gets the Thread join timeout used to join threads if no explicit timeout is set.- Returns:
- the timeout millis.
- Since:
- 1.10.2
-
setThreadJoinTimeout
public static void setThreadJoinTimeout(long millis)
Sets the Thread join timeout used to join threads if no explicit timeout is set.- Parameters:
millis
- the maximum time in milli-seconds to wait for a Thread to join if no explicit timeout has been set.- Since:
- 1.10.2
-
isAllowSNMPv2InV1
public static boolean isAllowSNMPv2InV1()
-
setAllowSNMPv2InV1
public static void setAllowSNMPv2InV1(boolean allowSNMPv2InV1)
Sets the compatibility flag for Counter64 usage in SNMPv1 PDUs and the ability to decode SNMPv2 traps in SNMPv1 version PDUs. The default isfalse
. Note: By setting this totrue
you disable SNMP standard conformity.- Parameters:
allowSNMPv2InV1
- if set totrue
, SNMP4J will allow Counter64 objects in SNMPv1 PDUs although the SNMPv1 standard does not allow this. There are several buggy implementations which send such v1 PDUs.- Since:
- 2.2
-
getReportSecurityLevelStrategy
public static SNMP4JSettings.ReportSecurityLevelStrategy getReportSecurityLevelStrategy()
-
setReportSecurityLevelStrategy
public static void setReportSecurityLevelStrategy(SNMP4JSettings.ReportSecurityLevelStrategy reportSecurityLevelStrategy)
-
isNoGetBulk
public static boolean isNoGetBulk()
-
setNoGetBulk
public static void setNoGetBulk(boolean noGetBulk)
-
getEnterpriseID
public static int getEnterpriseID()
Gets the enterprise OID used for creating SNMP engine IDs and other enterprise specific identifiers.- Returns:
- an enterprise ID. For example 4976 as enterprise ID (IANA number) for AGENT++ (SNMP4J). This value should be changed for other enterprises (i.e., companies or organizations).
-
setEnterpriseID
public static void setEnterpriseID(int enterpriseID)
Sets the enterprise OID used for creating SNMP engine IDs and other enterprise specific identifiers.- Parameters:
enterpriseID
- the new enterprise ID.
-
getMaxEngineIdCacheSize
public static int getMaxEngineIdCacheSize()
Gets the maximum number of engine IDs to be hold in the cache of theMPv3
. A upper limit is necessary to avoid DoS attacks with unconfirmed SNMPv3 PDUs.- Returns:
- the maximum number, by default 50.000 (~2MB of cached data).
- Since:
- 2.3.4
-
setMaxEngineIdCacheSize
public static void setMaxEngineIdCacheSize(int maxEngineIdCacheSize)
Sets the maximum number of engine IDs that can be cached by theMPv3
.- Parameters:
maxEngineIdCacheSize
- the maximum number of engine IDs in the cache, by default 50.000 (~2MB of cached data).- Since:
- 2.3.4
-
getSnmp4jStatistics
public static SNMP4JSettings.Snmp4jStatistics getSnmp4jStatistics()
Get the SNMP4J statistics level.- Returns:
- the Snmp4jStatistics enum value.
- Since:
- 2.4.2
-
setSnmp4jStatistics
public static void setSnmp4jStatistics(SNMP4JSettings.Snmp4jStatistics snmp4jStatistics)
Sets the SNMP4J statistics level.- Parameters:
snmp4jStatistics
- the level of statistics to be collected by SNMP4J and provided throughCounterEvent
s.- Since:
- 2.4.2
-
isCheckUsmUserPassphraseLength
public static boolean isCheckUsmUserPassphraseLength()
-
setCheckUsmUserPassphraseLength
public static void setCheckUsmUserPassphraseLength(boolean checkUsmUserPassphraseLength)
-
getDefaultTimeoutMillis
public static long getDefaultTimeoutMillis()
Get the default timeout forAbstractTarget
.- Returns:
- the default timeout in milli seconds.
- Since:
- 3.5.0
-
setDefaultTimeoutMillis
public static void setDefaultTimeoutMillis(long defaultTimeoutMillis)
Set the default timeout forAbstractTarget
. The default of the default value is 1000 milli-seconds (= one second).- Parameters:
defaultTimeoutMillis
- the default timeout forTarget
s in milli seconds.- Since:
- 3.5.0
-
getDefaultNonPrintableEscapeCharacter
public static java.lang.Character getDefaultNonPrintableEscapeCharacter()
Gets the default non-printable character escape character. Ifnull
non-printableOctetString
and otherVariable
will be printed/formatted withVariable#toString()
as hexadecimal string. If nonnull
non-printable characters (seeOctetString.isPrintable()
) will be replaced by the given character in the output.- Returns:
- the escape character for non-printable characters.
- Since:
- 3.6.1
-
setDefaultNonPrintableEscapeCharacter
public static void setDefaultNonPrintableEscapeCharacter(java.lang.Character defaultNonPrintableEscapeCharacter)
Gets the default non-printable character escape character. Ifnull
non-printableOctetString
and otherVariable
will be printed/formatted withVariable#toString()
as hexadecimal string. If nonnull
non-printable characters (seeOctetString.isPrintable()
) will be replaced by the given character in the output.- Parameters:
defaultNonPrintableEscapeCharacter
- the escape character for non-printable characters.null
disables escaping.- Since:
- 3.6.1
-
isSecretLoggingEnabled
public static java.lang.Boolean isSecretLoggingEnabled()
Check if logging secrets with their secret value in any debug level is allowed (true
) or not (false
). This value isfalse
by default.- Returns:
true
if secret logging is enabled,false
otherwise.
-
setSecretLoggingEnabled
public static boolean setSecretLoggingEnabled(boolean enableSecretLogging)
Activates or deactivates the secret logging. Note: Disabling secret logging is possible at any time, but enabling it is only possible if it has not yet been disabled.- Parameters:
enableSecretLogging
-true
for enabling secret logging,false
otherwise. Enabling will work only initially.- Returns:
- the new status (
true
if secret logging is enabled,false
otherwise). - Since:
- 3.6.1
-
-