# Chapter 5 Software Management
###### tags: `WG4`

Software build is a subject of **versioning** and **maintenance** and as such cannot be broken.

### Vendor

The use of compression and ciphering for the content of the software build is left to vendor implementation. The only file which shall never be ciphered is the manifest.xml file

- It is also Vendor's responsibility to handle SW Build / package / file integrity check.

### slot

The O-RU provides a set of so called "software slots" or "slots".

**Each slot provides an independent storage location for a single software build**.

The number of slots offered by O-RU depends on the device’s capabilities.

At least two writable slots shall be available at the O-RU for failsafe update operation

Presence of read only slot is optional.

The size of individual software slots is fixed and determined by the O-RU's vendor and sufficient to accommodate the full software build

## 5.1 Software Package

The software package is delivered by the O-RU vendor.

**Each software package includes:**

- manifest.xml
- software files to be installed on O-RU

**The name of package should follow the following format:**

“<Vendor Code><Vendor Specific Field>[#NUMBER].EXT”

## D.2.3 o-ran-software-management.yang Module


## 5.2 Software Inventory

### **Pre-condition:**

M-Plane NETCONF session established.

### **Post-condition:**

NETCONF client successfully collected the software inventory information from NETCONF server


Software Inventory is fetched by a NETCONF Client using the NETCONF `get rpc` filtered over the software-slot container.

### The following information is provided by software-inventory reply message

- The response contains information about each software slot and its contents.
1. **name** - name of the software slot (the name is defined by the O-RU vendor)
2. **status** - status of the software package. Status of the package can be
- VALID - Slot contains a software build considered as proven valid.
- INVALID - software build is not currently used by O-RU. The software is considered by the O-RU as damaged (e.g. wrong CRC).
- Activation of a software slot containing an invalid software build shall be prohibited.
- Note: failed software install operation can cause a slot status to change to "Invalid".
- EMPTY - software slot does not contain a software package. Activation of an empty software slot shall be prohibited.
3. **active** - indicates if the software stored in particular slot is activated at the moment.
- True - software slot contains an activated software build. Active::True can be assigned only for slots with status "Valid". At any time, only one slot in the O-RU MUST be marked as Active::True. The O-RU shall reject activation for software slots with status "Empty" and "Invalid".
- False - software slot contains passive software build or is empty
4. **running** - informs if software stored in particular slot is used at the moment.
- True - software slot contains the software build used by the O-RU in its current run.
- False - software slot contains a software build not used by O-RU at the moment
5. **access** – informs about access rights for the current slot
- READ_ONLY – The slot is intended only for factory software, activation of such software slot means performing a factory reset operation and a return to factory defaults settings.
- READ_WRITE – slot used for updating software
6. **product-code** - product code provided by the vendor, specific to the product.
7. **vendor-code** - unique code of the vendor.
8. **build-id** - Identity associated with the software build. This id is used to find the appropriate build-version ****for the product consist of the vendor-code and the product-code.
9. **build-name** - Name of the software build.
10. **build-version** - Version of the software build for the product consist of the vendor-code and the product-code.
11. **files** – list of files in build
12. **name** – name of one particular file
13. **version** – version of the file
14. **local-path** - complete path of the file on local file system
15. **integrity** - result of the file integrity check
- OK – file integrity is correct
- NOK – file is corrupted

If a slot contains a file with `integrity::NOK`, the O-RU shall mark the whole slot with `status::INVALID.`

## 5.3 Download

### Pre-condition:

- M-Plane NETCONF session established.
- O-RU Controller has subscribed to receive download-event notifications.

### Post-condition:

- O-RU downloads all files specified and successfully stores the downloaded files in the O-RU’s file system


Following types of authentications are supported for software-download:

1. password for RU authentication and list of public keys (DSA/RSA) for sFTP server authentication
2. certificate for both RU and sFTP server authentication

### roles

NETCOF client 、NETCONF server、sFTP

### request

The software-download rpc is used to trigger the downloading of software to the O-RU. The download shall be performed using sFTP. The rpc specifies the URI of the remote location of the software files.

### reply status

The O-RU shall send an immediate rpc-reply message with one of following statuses:

1. **TARTED** – software download operation has been started
2. **FAILED** – software download operation could not be proceeded, reason for failure in error-message

### notification complete or fail

When the O-RU completes the software download or software download fails, the O-RU shall send NETCONF download event notification with one of the following statuses:

1. **COMPLETED**
2. **AUTHENTICATION_ERROR**
- source available, wrong credentials
3. **PROTOCOL_ERROR**
- sFTP protocol error
4. **FILE_NOT_FOUND**
- source not available
5. **APPLICATION_ERROR**
- operation failed due to internal reason
6. **TIMEOUT**
- source available, credentials OK, Operation timed out (e.g. source becomes unavailable during ongoing operation)

The above will be repeated until all files which are required for the O-RU and which belong to the software package have been downloaded to the O-RU.

## 5.4 Install

### Pre-condition:

M-Plane NETCONF session established.

At least one software slot with status active::False and running::False exists in O-RU.

Software Download has been completed successfully and files are available in O-RU.

O-RU Controller has subscribed to receive install-event notifications.

### Post-condition:

O-RU software is installed in the specified target software-slot.


### request software-install

NETCONF software-install rpc is used to install the previously downloaded software (all files provided in the package) to the specified target software-slot on O-RU. This slot must have status active::False and running::False.

### reply status

The O-RU shall send an immediate rpc-reply message with one of following statuses:

1. **STARTED** – software install operation has been started.
2. **FAILED** – software install operation could not be proceeded, reason for failure in error-message.

### install-event notification

1. **COMPLETED** - Install procedure is successfully completed
2. **FILE_ERROR** – operation on the file resulted in in error, disk failure, not enough disk space, incompatible file format
3. **INTEGRITY_ERROR** – file is corrupted
4. **APPLICATION_ERROR** – operation failed due to internal reason

> When the software install commences, the O-RU shall set the slot status to INVALID. After the install procedure finishes, the O-RU shall change the slot status to its appropriate status.

## 5.5 Activation

### Pre-condition:

M-Plane NETCONF session established.

Software slot to be activated has status VALID.

O-RU Controller has subscribed to receive activation-event notifications.

### Post-condition:

O-RU software activates to the version of software-slot.


### software-activate rpc

NETCONF software-activate rpc is used to activate the software. The name of the software-slot is specified in the activate request.

### reply status

The O-RU shall send an immediate rpc-reply message with one of following statuses

1. **STARTED** – software activation operation has been started
2. **FAILED** – software activation operation could not be proceeded, reason for failure in error-message

### activation-event notifications

1. **COMPLETED** - Activation procedure is successfully completed. O-RU must be restarted via NETCONF reset rpc for the new software to be activated.
2. **APPLICATION_ERROR** - operation failed due to internal reason

Thus, successful software-activate command will set active::True to the slot that was provided in the rpc and automatically will set active::False to the previously active slot.

### reset

NETCONF reset rpc shall be sent to O-RU to activate to the version of the software-slot. O-RU restarts and performs startup procedure as described in Chapter 3 as regular startup with new software version running.

## 5.6 Software update scenario


## 5.7 Factory Reset

O-RU can be reset to the factory default software by activating the software-slot containing the factory default software and initiating NETCONF reset rpc. O-RU may clear persistent memory data during factory reset as vendor implementation option.