Docs 01 to 04 prepared for Rel SEVEN, fix references in 01, 04 and 05

Open Source MANO (OSM) is an ETSI-hosted open source community delivering a production-quality MANO stack for NFV, capable of consuming openly published information models, available to everyone, suitable for all VNFs, operationally significant and VIM-independent. OSM is aligned to NFV ISG information models while providing first-hand feedback based on its implementation experience.

Release SIX brings a number of improvements over previous releases. For the full list of new features, please refer to the [Release SIX Documentation](index.md). For a comprehensive overview of OSM functionalities, you can also refer to the [OSM Scope and Functionality White Paper](https://osm.etsi.org/images/OSM_EUAG_White_Paper_OSM_Scope_and_Functionality.pdf) or to the release notes of previous OSM releases ([ONE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseONE-FINAL.pdf), [TWO](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTWO-FINAL.pdf), [THREE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTHREE-FINAL.pdf), [FOUR](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf), [FIVE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFIVE-FINAL.pdf)).

Release SEVEN brings a number of improvements over previous releases. For the full list of new features, please refer to the [Release SEVEN Documentation](index.md). For a comprehensive overview of OSM functionalities, you can also refer to the [OSM Scope and Functionality White Paper](https://osm.etsi.org/images/OSM_EUAG_White_Paper_OSM_Scope_and_Functionality.pdf) or to the release notes of previous OSM releases ([ONE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseONE-FINAL.pdf), [TWO](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTWO-FINAL.pdf), [THREE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseTHREE-FINAL.pdf), [FOUR](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFOUR-FINAL.pdf), [FIVE](https://osm.etsi.org/images/OSM-Whitepaper-TechContent-ReleaseFIVE-FINAL.pdf)).

**OSM in Practice**

**OSM in Practice**:

<iframe src="https://www.youtube.com/embed/kCFxPV67Adw?" width="640" height="360" frameborder="0" allowfullscreen="true" style="box-sizing: border-box;"></iframe>

- MINIMUM: 2 CPUs, 4 GB RAM, 20GB disk and a single interface with Internet access

- RECOMMENDED: 2 CPUs, 8 GB RAM, 40GB disk and a single interface with Internet access

- Base image:

  - [Ubuntu18.04 (64-bit variant required)](http://releases.ubuntu.com/18.04/), or

  - [Ubuntu16.04 (64-bit variant required)](http://releases.ubuntu.com/16.04/)

- Base image: [Ubuntu18.04 (64-bit variant required)](http://releases.ubuntu.com/18.04/)

Once you have prepared the host with the previous requirements, all you need to do is:

```bash

wget https://osm-download.etsi.org/ftp/osm-6.0-six/install_osm.sh

wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh

chmod +x install_osm.sh

./install_osm.sh

```

**TIP:** In order to facilitate potential trobleshooting later, it is recommended to save the full log of your installation process:

```bash

wget https://osm-download.etsi.org/ftp/osm-6.0-six/install_osm.sh

wget https://osm-download.etsi.org/ftp/osm-7.0-seven/install_osm.sh

chmod +x install_osm.sh

./install_osm.sh 2>&1 | tee osm_install_log.txt

```

You will be asked if you want to proceed with the installation and configuration of LXD, juju, docker CE and the initialization of a local docker swarm, as pre-requirements. Please answer "y".

Then, some dialog messages related to LXD configuration will be shown. This is what you have to answer:

#### Installation including optional components

You can include optional components in your installation by adding the following flags:

- Do you want to configure the LXD bridge? **Yes**

- Do you want to setup an IPv4 subnet? **Yes**

- *<< **Default values** apply for next questions >>*

- Do you want to setup an IPv6 subnet? **No**

- **VIM Emulator:** `--vimemu` (more information [here](04-vim-setup.md#vim-emulator))

- **Fault Management features with ELK:** `--elk_stack` (more information [here](05-osm-usage.md#fault-management))

If you want to run docker commands, you will also need to either reload the shell or run the following command to add your user to the 'docker' group:

Example:

```bash

newgrp docker

./install_osm.sh --elk_stack --vimemu

```

#### Installation including optional components

#### Installation on a standalone Kubernetes environment

You can include optional components in your installation by adding the following flags:

From Release SEVEN, OSM can be deployed on a single host running a Kubernetes cluster. Although the default option is to use docker swarm, you can now tell the installer to use K8s as the container framework. The installer will install the required packages to run a single-node K8s cluster and will deploy the different K8s objects on it.

- **VIM Emulator:** `--vimemu` (more information [here](06-06-how-to-vim-emulator.md)

- **Performance Management additional stack (Grafana only):** `--pm_stack` (more information [here](06-03-01-performance-management.md)

- **Fault Management features with ELK:** `--elk_stack` (more information [here](06-03-02-fault-management.md)

```bash

./install_osm.sh -c k8s

```

Example:

In addition, you can use the option `--k8s\_monitor` to install an add-on to monitor the K8s cluster and OSM running on top of it.

```bash

./install_osm.sh --elk_stack --pm_stack --vimemu

./install_osm.sh -c k8s --k8s_monitor

```

#### Other installation options

- You can also run OSM using a pre-built [vagrant](https://app.vagrantup.com/osm/boxes/releasesix) image: [How_to_run_OSM_on_Vagrant](04-01-running-on-vagrant.md)

- For other special installation options, please refer to the [release documentation](04-04-advanced-install.md).

- You can also run OSM using a pre-built [vagrant](https://app.vagrantup.com/osm/boxes/releaseseven) image: [How_to_run_OSM_on_Vagrant](03-installing-osm.md#Vagrant-installation)

- For other special installation options, please refer to the [release documentation](index.md).

### Checking your installation

![OSM installation result](assets/600px-Osm_lwb_ui.png)

As a result of the installation, thirteen docker containers are created in the host (without considering optional stacks). You can check they are running by issuing the following commands:

As a result of the installation, fourteen docker containers are created in the host (without considering optional stacks). You can check they are running by issuing the following commands:

```bash

docker stack ps osm |grep -i running

docker service ls

```

If the previous docker commands do not work, you might need to either reload the shell (logout and login) or run the following command to add your user to the 'docker' group in the running shell:

```bash

newgrp docker

```

![OSM Docker containers](assets/600px-Osm_containers_rel5.png)

At any time, you can quickly relaunch your deployment by using the pre-built docker images, like this:

```bash

docker stack rm osm && sleep 60 # The sleep is for making sure the stack removal finishes before redeploying

docker stack rm osm

docker stack deploy -c /etc/osm/docker/docker-compose.yaml osm

```

OSM client, a python-based CLI for OSM, will be available as well in the host machine. Via the OSM client, you can manage descriptors, NS and VIM complete lifecycle.

#### Checking your installation when installing on K8s

As a result of the installation, different K8s objects (deployments, statefulsets, etc.) created in the host. You can check the status by running the following commands:

```bash

kubectl get all -n osm

```

To check the logs of any container:

```bash

kubectl logs -n osm deployments/lcm           # for LCM

kubectl logs -n osm deployments/light-ui      # for LW-UI

kubectl logs -n osm deployments/mon           # for MON

kubectl logs -n osm deployments/nbi           # for NBI

kubectl logs -n osm deployments/pol           # for POL

kubectl logs -n osm deployments/ro            # for RO

kubectl logs -n osm deployments/keystone      # for Keystone

kubectl logs -n osm statefulset/kafka         # for Kafka

kubectl logs -n osm statefulset/mongo         # for Mongo

kubectl logs -n osm statefulset/mysql         # for Mysql

kubectl logs -n osm statefulset/prometheus    # for Prometheus

kubectl logs -n osm statefulset/zookeeper     # for Zookeeper

```

Finally, if you used the option `--k8s\_monitor` to install an add-on to monitor the K8s cluster and OSM, you can check the status in this way.

```bash

kubectl get all -n monitoring

```

## Adding VIM accounts

Before proceeding, make sure that you have a site with a VIM configured to run with OSM. Different kinds of VIMs are currently supported by OSM:

- **OpenVIM.** Check the following link to know how to install and use openvim for OSM: [OpenVIM installation](10-00-openvim-install.md). Openvim must run in 'normal' mode (not test or fake) to have real virtual machines reachable from OSM.

- **OpenStack.** Check the following link to learn how to configure OpenStack to be used by OSM: [Openstack configuration](05-02-openstack-configuration.md)

- **VMware vCloud Director.** Check the following link to learn how to configure VMware VCD to be used by OSM: [Configuring VMware vCloud Director](11-vcd-configuration.md)

- **Amazon Web Services (AWS).** Check the following link to learn how to configure AWS (EC2 and Virtual Private Cloud) to be used by OSM: [Configuring AWS for OSM](12-aws-configuration.md)

- **Eclipse fog05** Check the following link to learn how to configure Eclipse fog05 to be used by OSM: [Configuring Eclipse fog05 for OSM](13-fog05-configuration.md)

- **OpenVIM.** Check the following link to know how to install and use openvim for OSM: [OpenVIM installation](13-openvim-installation.md). Openvim must run in 'normal' mode (not test or fake) to have real virtual machines reachable from OSM.

- **OpenStack.** Check the following link to learn how to configure OpenStack to be used by OSM: [Openstack configuration](04-vim-setup.md#Openstack)

- **VMware vCloud Director.** Check the following link to learn how to configure VMware VCD to be used by OSM: [Configuring VMware vCloud Director](04-vim-setup.md#VMware's-vCloud-Director)

- **Amazon Web Services (AWS).** Check the following link to learn how to configure AWS (EC2 and Virtual Private Cloud) to be used by OSM: [Configuring AWS for OSM](04-vim-setup.md#Amazon-Web-Services-(AWS))

- **Eclipse fog05** Check the following link to learn how to configure Eclipse fog05 to be used by OSM: [Configuring Eclipse fog05 for OSM](04-vim-setup.md#Fog05)

OSM can manage external SDN controllers to perform the dataplane underlay network connectivity on behalf of the VIM. See [EPA and SDN assist](05-01-how-to-epa-sdn-assist.md)

OSM can manage external SDN controllers to perform the dataplane underlay network connectivity on behalf of the VIM. See [EPA and SDN assist](04-vim-setup.md#Advanced-setups-for-high-I/O-performance:-EPA-and-SDN-Assist)

### Adding VIMs through OSM client

    --auth_url http://10.10.10.11:5000/v2.0 --tenant admin --account_type openstack

```

For advanced options, please refer to the [OpenStack Setup Guide](05-02-openstack-configuration.md#add-openstack-to-OSM).

For advanced options, please refer to the [OpenStack Setup Guide](04-vim-setup.md#Openstack).

#### VMware vCloud Director site

#### Uploading VM image(s) to the VIM(s)

In this example, only a vanilla CirrOS 0.3.4 image is need. It can be obtained from the following link: http://download.cirros-cloud.net/0.3.4/cirros-0.3.4-x86_64-disk.img

In this example, only a vanilla CirrOS 0.3.4 image is need. It can be obtained from the following link: <http://download.cirros-cloud.net/0.3.4/cirros-0.3.4-x86_64-disk.img>

If not available, it would be required to upload the image into the VIM. Instructions differ from one VIM to another:

- `keypair`: To be added in addition to the keypair allocated on the VNF descriptor. Provide the name of an openstack keypair

- `dataplane_physical_net`: The physical network label used in Openstack both to identify SRIOV and passthrough interfaces (nova configuration) and also to specify the VLAN ranges used by SR-IOV interfaces (neutron configuration). In case of VMware Integrated Openstack (VIO) provide moref ID of distributed virtual switch.

- `use_floating_ip`: (By default false). When boolean true, a management interface of a VNFD is automatically assigned a floating_ip -if possible-. If there is not any floating ip avalialble, it tries to get one if there is only one pool. You can use a string "pool_id" (public network id) instead of boolean true, to indicate the pool to use in case there are several. Note that deployment is not aborted if failing to asign a floating ip. The preferred method instead of this is to use a provider network

- `dataplane_net_vlan_range`: In case of VMware Integrated Openstack (VIO) provide vlan ranges for the SRIOV (binding direct) networks in format ['start_ID - end_ID']

- `use_floating_ip`: (By default false). When boolean true, a management interface of a VNFD is automatically assigned a floating\_ip -if possible-. If there is not any floating ip avalialble, it tries to get one if there is only one pool. You can use a string `pool_id` (public network id) instead of boolean true, to indicate the pool to use in case there are several. Note that deployment is not aborted if failing to asign a floating ip. The preferred method instead of this is to use a provider network

- `dataplane_net_vlan_range`: In case of VMware Integrated Openstack (VIO) provide vlan ranges for the SRIOV (binding direct) networks in format ['start\_ID - end\_ID']

- `microversion`: This is an Openstack-only parameter that allows to specify a specific microversion to be used in nova. When using `microversion: 2.32`, it enables the use of Virtual Device Role Tagging, which allows to identify each VM interface with a tag (the tag will be the name of the interface in the VNFD) and convey that information to the VM as metadata. This implementation approach is due to the warning message in <https://developer.openstack.org/api-guide/compute/microversions.html> where it is stated that microversion backwards compatibility is not guaranteed and clients should always require a specific microversion. This functionality was introduced would not work with Openstack versions previous to Newton.

- `no_port_security_extension`: Use for those OpenStack that do not have the port_security_extension. This property allows neutron to disable the port security. If this option is set, port security will never be disabled regardless of the descriptor indication.

- `disable_network_port_security`: Use for those OpenStack VIMs that do not support port security enabled at network level (although port_security_extension is present). This property allows neutron to disable the port security by default at the time of network creation for all ports created on the created networks.

- `no_port_security_extension`: Use for those OpenStack that do not have the port\_security\_extension. This property allows neutron to disable the port security. If this option is set, port security will never be disabled regardless of the descriptor indication.

- `disable_network_port_security`: Use for those OpenStack VIMs that do not support port security enabled at network level (although port\_security\_extension is present). This property allows neutron to disable the port security by default at the time of network creation for all ports created on the created networks.

The content of the config is a text formatted in yaml. The recommendation is to use a comma separated list between curly brackets `{}` and quotes `""`.

- `admin_username`: (Mandatory)Admin user

- `admin_password`: (Mandatory) Admin password

- `nsx_manager`: (Mandatory). NSX manager host name

- `nsx_user`: (Mandatory). nsx_user

- `nsx_password`: (Mandatory). nsx_password

- `nsx_user`: (Mandatory). nsx\_user

- `nsx_password`: (Mandatory). nsx\_password

- `vcenter_port`: (Mandatory).vCenter port

- `vcenter_user`: (Mandatory) vCenter username

- `vcenter_password`: (Mandatory). vCenter password

AWS provides a default `security_group` defining a set of rules that allow connection access to the instances that have this `security_group`. In case, you require a new `security_group` you can create a new group defining the conditions that are required by your use case.

Default `security_group` doesn't allow user to SSH into the instances. This behavior is not recommended by OSM, as VCA requires a path to interact with instances. Hence, it is recommended that you create a new group that contains the rules/conditions required to SSH into the instances deployed by this NS. You can also modify the default security group to allow TCP port 22 or, however, creation of a custom security_group is recommended.

Default `security_group` doesn't allow user to SSH into the instances. This behavior is not recommended by OSM, as VCA requires a path to interact with instances. Hence, it is recommended that you create a new group that contains the rules/conditions required to SSH into the instances deployed by this NS. You can also modify the default security group to allow TCP port 22 or, however, creation of a custom security\_group is recommended.

### Adding AWS as VIM target to OSM

The following configuration can be added:

- `management_network_id`, `management_network_name`: VIM management network id/name to use for the management VLD of NS descriptors. By default it uses same vim network name as VLD name. It can be set also at instantiation time.* `region_name`: Region to be used for the deployment

- `management_network_id`, `management_network_name`: VIM management network id/name to use for the management VLD of NS descriptors. By default it uses same vim network name as VLD name. It can be set also at instantiation time.

- `region_name`: Region to be used for the deployment

- `vpc_cidr_block`: Default CIDR block for VPC

- `security_groups`: Default security group for newly created instances

ADVANCED configuration:

- `key_pair`: Key_pair specified here will be used default key_pair for newly created instances

- `flavor_info`: AWS doesn't provide a mechanism to extract information regarding supported flavors. In order to get flavor information, user must specify a YAML file with the path such as: "@/usr/data/flavour_info.yaml" or user can specify a dictionary containing details of flavors to be used.

- `key_pair`: Key\_pair specified here will be used default key\_pair for newly created instances

- `flavor_info`: AWS doesn't provide a mechanism to extract information regarding supported flavors. In order to get flavor information, user must specify a YAML file with the path such as: "@/usr/data/flavour\_info.yaml" or user can specify a dictionary containing details of flavors to be used.

For specification of flavor info at time of datacenter creation use a parameter at `--config` called e.g. `flavor_info:`. The content must be a string. It can be a file starting with '@' that contains the info in YAML format, or directly the yaml content.

The following configuration can be added:

- `arch`: cpu architecture used when creating the VDUs for this VIM account eg. x86_64, aarch64, default is x86_64.

- `arch`: cpu architecture used when creating the VDUs for this VIM account eg. x86\_64, aarch64, default is x86\_64.

- `hypervisor`: hypervisor supported by this VIM account, can be one of: LXD, KVM, BARE, DOCKER, XEN, at least one node of the system as to be able to manage the selected hypervisor, default is LXD.

- `nodes`: if you want this VIM account to be able to manage only a subset of the nodes in the system you can pass a list of node uuids, by default is an empty list that means all nodes.

#### VLAN configuration (optional)

If you want your fog05 installation to be able to use VLANs for virtual networks instead of overlay VxLANs you need to change the configuration on all nodes. You need to update the configuration file /etc/fos/plugins/linuxbridge/linuxbridge_plugin.json

If you want your fog05 installation to be able to use VLANs for virtual networks instead of overlay VxLANs you need to change the configuration on all nodes. You need to update the configuration file `/etc/fos/plugins/linuxbridge/linuxbridge_plugin.json`.

```json

{

Here you can find and example of network service that can be instantiated to the Eclipse fog05 VIM using OSM. The network service is composed by a single VNF based on an Alpine Linux LXD image.

**`alpinevnfd.yaml`** vnfd:vnfd-catalog:

**`alpinevnfd.yaml`**:

```yaml

vnfd:vnfd-catalog:

   vnfd:

   -   id: alpine_vnfd

       name: alpine_vnf

However, ot all VIMs support EPA necessarily. To overcome this limitation, OSM has added the following two features:

- Since OSM Release ONE (October 2016), OSM includes OpenVIM as a reference VIM, with full support of EPA. You can follow the instructions in this **[link](10-00-openvim-install.md)** to install and use OpenVIM.

- Since OSM Release TWO (April 2017), OSM includes a new capability in the Resource Orchestrator called **[SDN Assist](05-01-how-to-epa-sdn-assist.md#sdn-assist)**. Through this capability, OSM can manage the dataplane underlay conectivity through an external SDN controller. The only requirement for the VIM is that it must able to use SR-IOV and/or passthrough interfaces, and expose the assigned interfaces so that the RO can use them to create the underlay connectivity. By default, the SDN Assist capability is disabled when a datacenter or VIM is added to OSM, but you can instruct OSM to enable it per VIM target.

- Since OSM Release ONE (October 2016), OSM includes OpenVIM as a reference VIM, with full support of EPA. You can follow the instructions in this **[link](13-openvim-installation.md)** to install and use OpenVIM.

- Since OSM Release TWO (April 2017), OSM includes a new capability in the Resource Orchestrator called **[SDN Assist](#SDN-Assist)**. Through this capability, OSM can manage the dataplane underlay conectivity through an external SDN controller. The only requirement for the VIM is that it must able to use SR-IOV and/or passthrough interfaces, and expose the assigned interfaces so that the RO can use them to create the underlay connectivity. By default, the SDN Assist capability is disabled when a datacenter or VIM is added to OSM, but you can instruct OSM to enable it per VIM target.

### SDN Assist

- <https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/10/html-single/network_functions_virtualization_planning_guide/>

- <https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/10/html-single/network_functions_virtualization_configuration_guide/>

- <https://docs.openstack.org/newton/networking-guide/config-sriov.html>

###### Additional notes

- Available attributes and values can be directly explored at the [OSM Information Model](03-03-osm-im.md)

- Available attributes and values can be directly explored at the [OSM Information Model](11-osm-im.md)

- A complete VNFD example can be downloaded from [here](https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/webserver_vimmetric_autoscale_vnfd.tar.gz).

- Normalized metric names are: `cpu_utilization`, `average_memory_utilization`, `disk_read_ops`, `disk_write_ops`, `disk_read_bytes`, `disk_write_bytes`, `packets_received`, `packets_sent`, `packets_out_dropped`, `packets_in_dropped`

Additional notes:

- Available attributes and values can be directly explored at the [OSM Information Model](03-03-osm-im.md)

- Available attributes and values can be directly explored at the [OSM Information Model](11-osm-im.md)

- A complete VNFD example with VNF metrics collection (VNF-level) can be downloaded from [here](https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfmetric_autoscale_vnfd.tar.gz).

###### 2) VDU-level VNF metrics

Additional notes:

- Available attributes and values can be directly explored at the [OSM Information Model](03-03-osm-im.md)

- Available attributes and values can be directly explored at the [OSM Information Model](11-osm-im.md)

- A complete VNFD example with VNF metrics collection (VDU-level) can be downloaded from [here](https://osm-download.etsi.org/ftp/osm-4.0-four/4th-hackfest/packages/ubuntuvm_vnfvdumetric_autoscale_vnfd.tar.gz).

As in VIM metrics, a list of "metrics" is defined first either at the VNF or VDU "configuration" level, which contain a name that comes from the metrics.yaml file. Then, at the VNF level, a list of monitoring-params is referred, with an ID, name, aggregation-type and their source, which can be a "vdu-metric" or a "vnf-metric" in this case.