masfcnv - SNMP configuration migration script
/usr/lib/net-snmp/masfcnv [-cimnrs] [-l agentmaster] [-p enabledisableerror] [-t noneadd] [-u agentmastererror] [-y agentmastererror] masfcnv [-V] masfcnv [-?]
System Administration Commands masfcnv(8)
NAME
masfcnv - SNMP configuration migration script
SYNOPSIS
/usr/lib/net-snmp/masfcnv [-cimnrs] [-l agentmaster]
[-p enabledisableerror] [-t noneadd]
[-u agentmastererror] [-y agentmastererror]
masfcnv [-V]
masfcnv [-?]
DESCRIPTION
The masfcnv script is used to assist the system administrator in
migrating an existing set of configuration files for the Sun SNMP Man-
agement Agent for Sun Fire and Netra Systems (MASF) to the Systems Man-
agement Agent (SMA).
The script accepts as input the currently installed set of MASF and SMA
configuration files and outputs a new set of SMA configuration files.
Existing SMA configuration files are backed up by appending .bak to the
filename. The administrator can choose to output the new configuration
to standard output, instead of replacing the current configuration, by
specifying the -n option.
The migration script must be run as the superuser. Failure to do so
causes the script to exit with an error message. Before running the
script you should ensure that both the SMA and MASF agents are not run-
ning. If the agents are running they will be shut down by the script.
The migration script installs a new startup script for the MASF agent
in /etc/init.d, as well as a backup of the old script. During migra-
tion, MASF will be configured as an AgentX subagent of SMA. All migra-
tion settings will be migrated to the SMA configuration file.
The migration script aborts if any unrecognized directives are found in
either the MASF configuration files or the SMA configuration files.
This can be overridden with the -i option. If this option is selected,
the behavior is to retain unrecognized directives that were present in
the SMA configuration, but remove those present in the MASF configura-
tion.
The migration script then proceeds to migrate access control and trap
configuration. As a side effect of running the migration script, the
following directives might be expanded by the script into multiple
directives with an equivalent interpretation:
o rwcommunity
o rocommunity
o rwuser
o rouser
o trapcommunity
o trapsink
o trap2sink
o informsink
Access Control Migration
Access control directives are expanded into the equivalent com2sec,
group, access and view directives. Existing group names are renamed by
prepending a prefix to avoid conflict with any which may already be
defined in SMA.
When migrating SNMPv1 or v2c access control, a conflict can occur if
both MASF and SMA configuration files have defined access permissions
for the same community and source address. The default behavior is to
abort with a message, unless a use of the -y option specifies other-
wise. If -y agent is specified then the MASF configuration takes prece-
dence. If -y master is specified then the SMA configuration is
retained.
When migrating USM configuration (SNMPv3), a conflict can occur if both
SMA and MASF configurations define a user with the same securityName.
If this occurs, the behavior of the script is determined by the -u
option. If -u agent is specified, the configuration of the user defined
in the MASF configuration files is the one that is retained. Otherwise,
if the -u master option is specified, the use defined in the SMA con-
figuration files is retained.
By default, the migration script attempts to migrate USM users from
MASF to SMA. The script determines whether there are any SNMPv3 users
present in the SMA configuration and whether the default engineID has
been overridden in the SMA configuration files. If neither of these
conditions obtain, then the any usmUser statements containing localized
authentication keys can be migrated to SMA, along with the MASF
engineID. This results in the engineID of the SMA master agent chang-
ing.
If the script determines that there are existing SNMPv3 users or a man-
ually configured engineID present in the SMA configuration, only those
users defined in createUser statements are transferred. Those users
that were defined in usmUser statements are transferred but will have
their passwords reset to a random value. You should notify your users
of their new password or reset the password yourself by editing the
newly-generated configuration file.
Trap/Inform Migration
The migration script performs a check to determine whether a trap des-
tination defined for MASF is already specified in an existing SMA
trapsink, trap2sink or informsink directive. If this is the case, then
the directive in the MASF configuration will be discarded to avoid
duplicate traps/informs being received.
trapsink, trap2sink and informsink directives specified in the existing
SMA configuration are considered valid destinations for MASF
traps/informs and will receive them from the MASF subagent after migra-
tion.
If the -t none option was specified on the command line, the migration
script carries over any remaining MASF trap/inform directives without
modification.
If the -t add option was specified (the default), the migration script
expands any trapsink, trap2sink, or informsink directives to use the
TARGET-MIB and NOTIFICATION-MIB. The TARGET-MIB specifies targets using
IP addresses, so it might be desirable to use the -t none option if,
for example, the network allocates IP addresses to hostnames dynami-
cally by means of DHCP.
The expanded directives defines filters specific to the MASF agent so
that traps from other subagents will not be received by migrated trap
destinations. Existing filters present in the SMA configuration are, by
default, not modified and might or might not receive MASF traps,
depending upon the filters that were originally defined for them.
If the -l option is specified, any filters already defined in the TAR-
GET-MIB and the NOTIFICATION-MIB for SMA are extended to include traps
from MASF. In the event that a trap destination is already configured
in the TARGET-MIB with the same target address and community as an
existing MASF trap/inform sink, a conflict will arise.
If -l agent was specified and a conflict arises, the migration script
uses the target SNMP parameters (that is, the SNMP version and choice
of trap/inform) defined by the MASF trap/informsink directive to send
traps to this destination. Otherwise, if the -l master option was spec-
ified, the conflict will be resolved using the target SNMP parameters
specified in the SMA configuration.
Miscellaneous
If the migration script encounters in the MASF configuration file any
of the directives listed below and the directives are either not
present or differ from the SMA configuration, the script will log a
warning message.
o syslocation
o syscontact
o sysname
o sysservices
o agentgroup
o agentuser
o authtrapenable
OPTIONS
The following options are supported:
-?
--help
Displays usage information.
-c
--no-community
Do not transfer v1/v2c communities.
-i
--ignore-unrecognized-directives
Continue processing if unrecognized directives are present.
-l agent | master
--master-trap-target=agent | master
If agent is specified, the existing SMA trap targets will be con-
figured to receive traps that were previously sent to destinations
for the Sun Fire SNMP agent. If master is specified, the targets
will be configured to receive Sun Fire SNMP traps, but existing
SNMP target parameters will be used.
-m
--no-usmuser
Do not transfer usm (v3) users.
-n
--dry-run
Run the migration without modifying any files. If an error arises,
continue processing. This can be used to determine the likely
migration issues.
-p enable | disable | error
--use-agent-port=enable | disable | error
Indicates whether the port originally used by the Sun Fire SNMP
agent should be used by the SMA agent after migration (if the two
agents are using different ports). If enable is specified, then the
port used by the Sun Fire SNMP agent will also be used by the SMA
agent after migration. If disable is specified, the ports used by
SMA will not be updated by the migration tool. If the error option
is specified and the SMA agent is not already using the same ports
as those used by the original Sun Fire SNMP agent, an error is
reported and the migration process is terminated. If no option is
specified the default behavior is equivalent to the error flag.
-r
--no-trap
Do not transfer trap destinations.
-s
--skip-user
If a user is found in the MASF configuration file that cannot be
created in the new configuration because of a change in the engine
ID, then output a message indicating that the user could not be
migrated (needs to be manually recreated) and continue processing.
If this option is not present, the migration tool will consider
such a situation as an error and abort.
-t none | add
--trap-filter=none | add
If none is specified then the script will copy trap directives
directly. The administrator might need to manually update the con-
figuration file to ensure traps are only delivered to their
intended destinations. If add is specifed, trap filters will be
constructed so that traps originating from the original Sun Fire
SNMP agent are delivered only to the destinations that originally
received them. The default behavior is add.
-u agent | master | error
--select-user=agent | master | error
Specifies that if a user with the same name is found in both con-
figuration files that the conflict is to be resolved using the
specified configuration file as input. Selecting a user from a par-
ticular file will also cause the group declaration for that user to
be taken from the same file. If agent is specified then the user
will be taken from the configuration file for the Sun Fire SNMP
Agent. If master is specified, the user will be taken from the SMA
configuration. Otherwise, if error is given, the script will termi-
nate. If this option is not present, the default behavior is equiv-
alent to the error flag.
-V
--version
Display the version of this script.
-y agent | master | error
--select-community=agent | master | error
Specifies that if a community with the same name is found in both
configuration files that the conflict is to be resolved using the
specified configuration file as input. If agent is specified then
the community will be taken from the configuration file for the Sun
Fire SNMP Agent. If master is specified, the community will be
taken from the SMA configuration. Otherwise, if error is given, the
script will terminate. If this option is not present, the default
behavior is equivalent to the error flag.
EXAMPLES
Example 1 Simplest Case
The command shown below is appropriate for a simple migration. The
migration fails if there are any potential conflicts.
# masfcnv
Example 2 Migrating Such That MASF Settings Override
To migrate the MASF configuration such that it will always succeed,
that MASF settings will override in the event of a conflict with SMA,
and that access will still be provided on the original MASF port,
enter:
# masfcnv -is -l agent -p enable -u agent -y agent
Example 3 Dry Run, Retaining SMA Settings
To attempt a dry run and migrate the configuration such that any con-
flicts will be resolved by retaining existing SMA settings, enter:
masfcnv -l master -u master -y master
EXIT STATUS
0 Success.
non-zero A problem occurred during migration.
FILES
/etc/sma/snmp/snmpd.conf
/var/sma_snmp/snmpd.conf
SMA configuration files
/etc/opt/SUNWmasf/conf/snmpd.conf
/var/opt/SUNWmasf/snmpd.dat
MASF configuration files
/tmp/sma_migration.log
masfcnv log file
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+-----------------------------+----------------------------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+----------------------------------------------+
|Availability |system/management/snmp/net-snmp/documentation |
+-----------------------------+----------------------------------------------+
|Interface Stability |Volatile |
+-----------------------------+----------------------------------------------+
SEE ALSO
attributes(7)
NOTES
The former path to this utility, /usr/sfw/lib, is now a link to
/usr/lib.
Solaris 11.4 28 Oct 2015 masfcnv(8)