##### Welcome #####
This file contains supplementary information related to configuration of a Python script used by operational instruction "Rehoming with EvoC RNCs and ENM"
For general description of the script use, refer to official Customer Documentation.


### Script maintenance ###
The script is being maintained by WCDMA RNC design organization.
Issues should be reported using TR process via MHWeb using a product number CYA 901 0756 (responsible MHO is 3G-RNC-PLM).


### The Rehoming script ###
The rehoming script is a Python program which is deployed as a part of AMOS software on ENM. Its files are located in following directory:
/opt/ericsson/amos/moshell/commonjars/scripts/rehoming/

Directory contents:
- "rnc_radio_backup.py" - main executable file
- "functions.py", "rnc_node_module.py" - modules imported by main executable
- "config.ini" - example of configuration file containing dummy IP values for spare and live RNCs
	This file should be copied by user to "/ericsson/log/amos/moshell_logfiles/$USER/logs_rehoming/" and modified
- "CHANGELOG.md" - text file containing script versions history
- "DESCRIPTION.txt" - description of parameters present in configuration files

The rehoming script can be run only on the ENM scripting VM. Its purpose is to produce a backup file containing specific live RNC radio configuration in a form of AMOS .mo file.


### Configuration file syntax ###
Script uses a standard Python library for configuration file parsing.
Please refer to [ConfigParser] documentation for more details about syntax used in configuration files. (See https://docs.python.org/2/library/configparser.html)


### Content of configuration file ###
The configuration file consists of sections led by a "[section]" header and followed by "name = value" entries.
The script requires four mandatory sections: "[parameters]", "[spare_rnc]", "[live_rnc]" and "[mo_filter]". Lines starting with # denote comments and are ignored.
The names of all parameters should be given in lower-case.

There are two types of parameters present in a configuration file:
- mandatory - script expects that this parameter is present and set correctly
- optional - script will use a default value if the parameter is missing


### Section "[parameters]" ###
Contains parameters which define the script behavior.

- mobatch_executable - mandatory - default: N/A
	+ Location of mobatch executable. Mobatch is used by the script to communicate with RNCs.

- mo_per_transaction - optional	- default: 300 - range: {0 .. infinity}
	+ Limit of number of MOs being created or set during each transaction. This value determines placing of "TRANSACTION BEGIN" and "TRANSACTION END" tags in resulting .mo file.
		Transactions allow optimization and faster execution of .mo script by reducing communication overhead and reducing RNC load.
		Higher value is expected to speed up the loading process but increases the risk of transaction timeout.
	+ Value 0 means that transactions are not used (tags will not be created in resulting .mo file).
	! Recommendation is not to exceed limit of 300 MOs per transaction.

- normal_transaction_delay - optional - default: 0 	- range: {0 .. infinity}
	+ Additional delay (in milliseconds) which is added after each transaction that does not contain any instance of MO class with 'Relation' in its name.
		This value determines duration of additional waiting time used for "WAIT" action in resulting .mo script after each transaction.
		If "mo_per_transaction = 0" and therefore transaction tags are not created, then the "WAIT" tags are added every 300 MOs.
		Purpose of this parameter is to slow down the loading of resulting .mo, for example to reduce network and RNC load.
	+ Value 0 means that additional "WAIT" tags are not created.

- relation_transaction_delay - optional	- default: 0 - range: {0 ..  infinity}
	+ Additional delay (in milliseconds) which is added after each transaction that has at least one instance of MO class with 'Relation' in its name.
		See description of "normal_transaction_delay" above for more details.

- system_created_mo - optional - default: ""
	+ List of System Created MO classes. MO class instances with given names will be handled differently by the script.
		Instead of CREATE action (which is illegal for System Created MOs), the script will use SETM action to set parameters for each instance of the MO class.

## Example of section content ##
[parameters]
mobatch_executable = /opt/ericsson/amos/bin/mobatch
mo_per_transaction = 300

# Transaction delays are in milliseconds (eg. value 2000 means 2 seconds)
normal_transaction_delay = 0
relation_transaction_delay = 0

# List of System Created MOs (script will set them instead of create)
system_created_mo = MultiCarrier; NodeSynch


### Section "[spare_rnc]" ###
This section contains an IP address of the spare RNC. Only one IP address can be specified in this section.

- spare_rnc - mandatory - Value: valid IP address: xxx.xxx.xxx.xxx
	+ The IP address of the spare RNC O&M interface. This address can be obtained from the ENM Topology Browser in "Node Details" from parameter ipAddress.

## Example of section content ##
[spare_rnc]
spare_rnc = 192.168.1.1


### Section "[live_rnc]" ###
This section contains IP addresses of all live RNCs which are planned to be backed up and eventually rehomed.
Naming of parameters in this section is decided by a user. Used names should be unique and follow recommended syntax.
Chosen RNC names are later used for file names created by rehoming script and to determine RNC for script actions.
It is required to configure at least one live RNC address in this section.

- live_rnc - mandatory - Value: valid IP address: xxx.xxx.xxx.xxx

## Example of section content ##
[live_rnc]
live_rnc1 = 192.168.1.2
live_rnc2 = 192.168.1.3
live_rnc3 = 192.168.1.4
live_rnc4 = 192.168.1.5


### Section "[mo_filter]" ###
Contains the ordered list of MO filters which define copied RNC Radio Configuration.
Naming of parameters in this section is decided by the user, although it is recommended to follow currently used naming convention (eg. mo_group_ss7_1, mo_group_sccp, mo_group01, mo_group02 etc.).
Used names should be unique and follow recommended syntax.

Each element of the list defines one ENM Export filter.
See ENM CLI manual for ["User-Defined Filter File" format]. (http://cpistore.internal.ericsson.com/elex?LI=EN/LZN7030220*&FN=1_1553-cna4032979uen.*.html&HT=bxf1539029488282)

Generally it is recommended to use the following clauses:
- `<MO Class>.<w>` to specify all instances of a given MO Class and its writable, persistent attributes
- `<MO Class>+.<w>` to specify all instances of a given MO Class and its writable, persistent attributes, together with all its sub-classes and attributes

Order of filters in the list determines the order in which the specified MO classes are exported from the ENM and also their place in resulting .mo file.
User needs to ensure that MO classes referenced by other MO classes are created earlier (eg. IubLink before UtranCell because of UtranCell.iubLinkRef attribute).
!! The rehoming script does not analyze MO references, which means it is up to the user to secure correct MO loading order. !!

## Default contents of [mo_filter] section ##
[mo_filter]
mo_group_ss7_1 = Mtp3bSpItu.<w>; Mtp3bSrs.<w>
mo_group_ss7_2 = M3uAssociation.<w>; Mtp3bAp.<w>; Mtp3bSls.<w>
mo_group_ss7_3 = Mtp3bSr.<w>
mo_group_sccp = SccpSp+.<w>
mo_group01 = IuLink+.<w>
mo_group02 = IubLink+.<w>
mo_group03 = IurLink+.<w>
mo_group04 = LocationArea+.<w>
mo_group05 = Ura+.<w>
mo_group06 = UtranCell.<w>; Fach+.<w>; Pch+.<w>; Rach+.<w>; AnrBlackList+.<w>; Hsdsch+.<w>
mo_group07 = UtranRelation+.<w>
mo_group08 = CoverageRelation+.<w>
mo_group09 = ExternalGsmNetwork+.<w>
mo_group10 = GsmRelation+.<w>
mo_group11 = EutraNetwork+.<w>
mo_group12 = EutranFreqRelation+.<w>
