10. ANNEX 2: Reference of OSM Client commands and library

The OSM Client is a client library and a command-line tool (based on Python) to operate OSM, which accesses OSM’s Northbound Interface (NBI) and lets you manage descriptors, VIMs, Network Services, Slices, etc. along with their whole lifecycle. In other words, the OSM Client is a sort of Swiss knife that provides a convenient access to all the functionality that OSM’s NBI offers.

Usage:

osm [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGS]...

Options:

  --hostname TEXT             hostname of server.  Also can set OSM_HOSTNAME in environment
  --user TEXT                 user (defaults to admin). Also can set OSM_USER in environment
  --password TEXT             password (defaults to admin). Also can set OSM_PASSWORD in environment
  --project TEXT              project (defaults to admin). Also can set OSM_PROJECT in environment
  -v, --verbose               increase verbosity (-v INFO, -vv VERBOSE, -vvv DEBUG)
  --all-projects              include all projects
  --public / --no-public      flag for public items (packages, instances, VIM accounts, etc.)
  --project-domain-name TEXT  project domain name for keystone authentication (default to None). Also can set OSM_PROJECT_DOMAIN_NAME in environment
  --user-domain-name TEXT     user domain name for keystone authentication (default to None). Also can set OSM_USER_DOMAIN_NAME in environment
  -h, --help                  Show this message and exit.

Commands:
  k8scluster-add             adds a K8s cluster to OSM NAME: name of the K8s cluster
  k8scluster-delete          deletes a K8s cluster NAME: name or ID of the K8s cluster to be deleted
  k8scluster-list            list all K8s clusters
  k8scluster-show            shows the details of a K8s cluster NAME: name or ID of the K8s cluster
  k8scluster-update          updates a K8s cluster
  netslice-instance-create   creates a new Network Slice Instance
  netslice-instance-delete   deletes a Network Slice Instance (NSI)
  netslice-instance-list     list all Network Slice Instances (NSI)
  netslice-instance-op-list  shows the history of operations over a Network Slice Instance (NSI)
  netslice-instance-op-show  shows the info of an operation over a Network Slice Instance(NSI)
  netslice-instance-show     shows the content of a Network Slice Instance (NSI)
  netslice-template-create   creates a new Network Slice Template (NST)
  netslice-template-delete   deletes a Network Slice Template (NST)
  netslice-template-list     list all Network Slice Templates (NST)
  netslice-template-show     shows the content of a Network Slice Template (NST)
  netslice-template-update   updates a Network Slice Template (NST)
  nf-list                    list all NF instances
  nfpkg-create               creates a new NFpkg
  nfpkg-delete               deletes a NFpkg
  nfpkg-list                 list all xNF packages (VNF, HNF, PNF)
  nfpkg-repo-list            list all xNF from OSM repositories
  nfpkg-repo-show            shows the details of a NF package in an OSM repository
  nfpkg-show                 shows the details of a NF package
  nfpkg-update               updates a NFpkg
  ns-action                  executes an action/primitive over a NS instance
  ns-alarm-create            creates a new alarm for a NS instance
  ns-create                  creates a new Network Service instance
  ns-delete                  deletes a NS instance
  ns-list                    list all NS instances
  ns-metric-export           exports a metric to the internal OSM bus, which can be read by other apps
  ns-op-list                 shows the history of operations over a NS instance
  ns-op-show                 shows the info of a NS operation
  ns-show                    shows the info of a NS instance
  nsd-create                 creates a new NSD/NSpkg
  nsd-delete                 deletes a NSD/NSpkg
  nsd-list                   list all NS packages
  nsd-repo-list              list all NS from OSM repositories
  nsd-repo-show              shows the details of a NS package in an OSM repository
  nsd-show                   shows the details of a NS package
  nsd-update                 updates a NSD/NSpkg
  nsi-create                 creates a new Network Slice Instance
  nsi-delete                 deletes a Network Slice Instance (NSI)
  nsi-list                   list all Network Slice Instances (NSI)
  nsi-op-list                shows the history of operations over a Network Slice Instance (NSI)
  nsi-op-show                shows the info of an operation over a Network Slice Instance(NSI)
  nsi-show                   shows the content of a Network Slice Instance (NSI)
  nspkg-create               creates a new NSD/NSpkg
  nspkg-delete               deletes a NSD/NSpkg
  nspkg-list                 list all NS packages
  nspkg-repo-list            list all NS from OSM repositories
  nspkg-repo-show            shows the details of a NS package in an OSM repository
  nspkg-show                 shows the details of a NS package
  nspkg-update               updates a NSD/NSpkg
  nst-create                 creates a new Network Slice Template (NST)
  nst-delete                 deletes a Network Slice Template (NST)
  nst-list                   list all Network Slice Templates (NST)
  nst-show                   shows the content of a Network Slice Template (NST)
  nst-update                 updates a Network Slice Template (NST)
  package-build              Build the tar.gz of the package
  package-create             Create a package descriptor
  package-validate           Validate a package descriptor
  pdu-create                 adds a new Physical Deployment Unit to the catalog
  pdu-delete                 deletes a Physical Deployment Unit (PDU)
  pdu-list                   list all Physical Deployment Units (PDU)
  pdu-show                   shows the content of a Physical Deployment Unit (PDU)
  project-create             creates a new project
  project-delete             deletes a project
  project-list               list all projects
  project-show               shows the details of a project
  project-update             updates a project (only the name can be updated)
  repo-add                   adds a repo to OSM NAME: name of the repo URI: URI of the repo
  repo-delete                deletes a repo NAME: name or ID of the repo to be deleted
  repo-list                  list all repos
  repo-show                  shows the details of a repo NAME: name or ID of the repo
  repo-update                updates a repo in OSM NAME: name of the repo
  role-create                creates a new role
  role-delete                deletes a role
  role-list                  list all roles
  role-show                  show specific role
  role-update                updates a role
  sdnc-create                creates a new SDN controller
  sdnc-delete                deletes an SDN controller
  sdnc-list                  list all SDN controllers
  sdnc-show                  shows the details of an SDN controller
  sdnc-update                updates an SDN controller
  upload-package             uploads a VNF package or NS package
  user-create                creates a new user
  user-delete                deletes a user
  user-list                  list all users
  user-show                  shows the details of a user
  user-update                updates user information
  version
  vim-create                 creates a new VIM account
  vim-delete                 deletes a VIM account
  vim-list                   list all VIM accounts
  vim-show                   shows the details of a VIM account
  vim-update                 updates a VIM account
  vnf-list                   list all NF instances
  vnf-scale                  executes a VNF scale (adding/removing VDUs)
  vnf-show                   shows the info of a VNF instance
  vnfd-create                creates a new VNFD/VNFpkg
  vnfd-delete                deletes a VNFD/VNFpkg
  vnfd-list                  list all xNF packages (VNF, HNF, PNF)
  vnfd-show                  shows the details of a NF package
  vnfd-update                updates a new VNFD/VNFpkg
  vnfpkg-create              creates a new VNFD/VNFpkg
  vnfpkg-delete              deletes a VNFD/VNFpkg
  vnfpkg-list                list all xNF packages (VNF, HNF, PNF)
  vnfpkg-repo-list           list all xNF from OSM repositories
  vnfpkg-repo-show           shows the details of a NF package in an OSM repository
  vnfpkg-show                shows the details of a NF package
  vnfpkg-update              updates a VNFD/VNFpkg
  wim-create                 creates a new WIM account
  wim-delete                 deletes a WIM account
  wim-list                   list all WIM accounts
  wim-show                   shows the details of a WIM account
  wim-update                 updates a WIM account

10.1. Installing standalone OSM Client

OSM client is installed by default in the host where OSM is installed, but it can be also installed as a standalone client.

10.1.1. Installing with debian package

In order to install the OSM Client in your local Linux machine, you should follow this procedure:

# Clean the previous repos that might exist
sudo sed -i "/osm-download.etsi.org/d" /etc/apt/sources.list
wget -qO - https://osm-download.etsi.org/repository/osm/debian/ReleaseTEN/OSM%20ETSI%20Release%20Key.gpg | sudo apt-key add -
sudo add-apt-repository -y "deb [arch=amd64] https://osm-download.etsi.org/repository/osm/debian/ReleaseTEN stable devops IM osmclient"
sudo apt-get update
sudo apt-get install -y python3-pip
sudo -H python3 -m pip install -U pip
sudo -H python3 -m pip install python-magic pyangbind verboselogs
sudo apt-get install python3-osmclient

10.1.2. Installing from git repo

# Ubuntu 18.04 pre-requirements
sudo apt-get install python3-pip libcurl4-openssl-dev libssl-dev
# CentOS pre-requirements
# sudo yum install python3-pip libcurl-devel gnutls-devel
sudo -H python3 -m pip install python-magic
# Install OSM Information model
sudo -H python3 -m pip install git+https://osm.etsi.org/gerrit/osm/IM --upgrade
# Install OSM client from the git repo.
# You can install the latest client from master branch in this way:
sudo -H python3 -m pip install git+https://osm.etsi.org/gerrit/osm/osmclient
# You could also install a specific tag/version in this way
sudo -H python3 -m pip install git+https://osm.etsi.org/gerrit/osm/osmclient@v8.0.0rc1

10.1.3. Installing from cloned repo (for developers)

# Ubuntu 18.04 pre-requirements
sudo apt-get install python3-pip libcurl4-openssl-dev libssl-dev
# Centos pre-requirements
# sudo yum install python3-pip libcurl-devel gnutls-devel
sudo -H python3 -m pip install python-magic pyangbind verboselogs
# Install OSM Information model
sudo -H python3 -m pip install git+https://osm.etsi.org/gerrit/osm/IM --upgrade
# Clone the osmclient repo and install OSM client from the git repo.
git clone https://osm.etsi.org/gerrit/osm/osmclient
cd osmclient
python3 -m pip install --user -e .
# logout and login so that PATH can be updated. Executable osm will be found in /home/ubuntu/.local/bin

To uninstall, just:

python3 -m pip uninstall osmclient

10.2. Getting help

Options -h or --helpcan be used globally to know the global options and commands, or after a command to know the specific options and args of a command

$ osm -h
Usage: osm [OPTIONS] COMMAND [ARGS]...

Options:
  --hostname TEXT             hostname of server.  Also can set OSM_HOSTNAME in environment
  --user TEXT                 user (defaults to admin). Also can set OSM_USER in environment
  --password TEXT             password (defaults to admin). Also can set OSM_PASSWORD in environment
  --project TEXT              project (defaults to admin). Also can set OSM_PROJECT in environment
  -v, --verbose               increase verbosity (-v INFO, -vv VERBOSE, -vvv DEBUG)
  --all-projects              include all projects
  --public / --no-public      flag for public items (packages, instances, VIM accounts, etc.)
  --project-domain-name TEXT  project domain name for keystone authentication (default to None). Also can set OSM_PROJECT_DOMAIN_NAME in environment
  --user-domain-name TEXT     user domain name for keystone authentication (default to None). Also can set OSM_USER_DOMAIN_NAME in environment
  -h, --help                  Show this message and exit.

Commands:
  k8scluster-add             adds a K8s cluster to OSM
  ...

$osm vim-create -h
Usage: osm vim-create [OPTIONS]

  creates a new VIM account

Options:
  --name TEXT              Name to create datacenter
  --user TEXT              VIM username
  --password TEXT          VIM password
  --auth_url TEXT          VIM url
  --tenant TEXT            VIM tenant name
  --config TEXT            VIM specific config parameters
  --account_type TEXT      VIM type
  --description TEXT       human readable description
  --sdn_controller TEXT    Name or id of the SDN controller associated to this VIM account
  --sdn_port_mapping TEXT  File describing the port mapping between compute nodes' ports and switch ports
  --wait                   do not return the control immediately, but keep it until the operation is completed, or timeout
  -h, --help               Show this message and exit.

The following video illustrates how it works.

10.3. Interaction from the OSM client to an OSM in a different location

When using the OSM Client from a host different from OSM’s, at a minimum you will need to specify the OSM host, either via an environment variable or via the option --hostname. For instance, you can set your client to access an OSM host running at 10.80.80.5 by using:

export OSM_HOSTNAME="10.80.80.5"

The following video shows how it works.

10.4. Getting OSM version

You can obtain server and client versions, by using the command osm version. Server version corresponds to OSM NBI module.

$ osm version
Server version: 7.0.1.post23 2020-04-17
Client version: 7.0.1rc1.post52+gbcb7833

The following video shows how it works.

10.5. RBAC

10.5.1. Configuring RBAC

OSM supports Role-Based Access Control, so that it’s possible to use users and projects, and each user will have a role in a project. OSM provides CRUD operations (*-create, *-list, *-show, *-update, *-delete) over users, roles and projects

The following video demonstrates how it works.

10.5.2. Using RBAC

When using users and projects, the following environment variables can be used to authenticate against the system:

OSM_USER
OSM_PASSWORD
OSM_PROJECT
OSM_PROJECT_DOMAIN_NAME
OSM_USER_DOMAIN_NAME

Or instead the command line options --user, --password, --project, --project-domain-name and --user-domain-name can be used:

  --user TEXT                 user (defaults to admin). Also can set OSM_USER in environment
  --password TEXT             password (defaults to admin). Also can set OSM_PASSWORD in environment
  --project TEXT              project (defaults to admin). Also can set OSM_PROJECT in environment
  --project-domain-name TEXT  project domain name for keystone authentication (default to None). Also can set OSM_PROJECT_DOMAIN_NAME in environment
  --user-domain-name TEXT     user domain name for keystone authentication (default to None). Also can set OSM_USER_DOMAIN_NAME in environment

In addition, the option --all-projects allow users to perform operations in all the projects they belong to (e.g. osm --all-projects nfpkg-list will show all the NF packages in all projects the user belongs to). Finally, the option --public allows to create public items, making them available in all projects; visibility from the client of those public items in *-list and *-show operations requires the use of the option --public.

  --all-projects              include all projects
  --public / --no-public      flag for public items (packages, instances, VIM accounts, etc.)

The following video shows a complete demo using different users and projects, and some of these options, illustrating the different project visibility.

10.6. OSM repositories

OSM support repositories where NF and NS packages can be retrieved. The following commands can be used to add a repo, list the packages in a repo, show their details or onboard them in OSM:

osm repo-add NAME URI: adds a VNF/NS catalog repo
osm nfpkg-repo-listand osm nspkg-repo-list: lists NF/NS packages from OSM repositories
osm nfpkg-repo-show|nspkg-repo-show --repo <REPO_NAME>: shows a specific NF/NS package in a repo
osm nfpkg-create|nspkg-create --repo <REPO_NAME> <OSM_PKG>: onboards a package from a repo into OSM

osm repo-add --description "OSM VNF and NS repository" vnfrepo https://osm-download.etsi.org/ftp/vnf-catalog/
osm nfpkg-repo-list
osm nfpkg-repo-show --repo vnfrepo fb_magma_knf
osm nfpkg-create --repo vnfrepo fb_magma_knf
osm nspkg-repo-list
osm nspkg-repo-show --repo vnfrepo fb_magma_ns
osm nspkg-create --repo vnfrepo fb_magma_ns

The following video demonstrates how these commands work.

10.7. Package creation tools

There are several utilities in the OSM client to simplify VNF and NS package creation:

osm package-create PACKAGE_TYPE PACKAGE_NAME: creates an OSM VNF, NS or NST package
osm package-validate PKG_FOLDER: validates descriptors given a base directory
osm package-build PKG_FOLDER: builds the package NS, VNF given the package_folder (descriptor validation, charm build, checksum generation, tar.gz creation)
osm nfpkg-create|nspkg-create PKG_FOLDER: validates the package, builds it and onboards it into OSM

The following video illustrates the previous commands.

10.8. Advanced onboarding

Commands for onboarding NF, NS and NST (nfpkg-create, nspkg-create and nst-create) have the option --override to override the fields in the descriptor whem uploading the package to OSM. The format of the option is the following:

  --override TEXT      overrides fields in descriptor, format: "key1.key2...=value[;key3...=value;...]"

In addition, VNF onboarding allows these additional options:

--override-epa: adds guest-epa parameters to all VDU. Useful to onboard packages to be deployed in an EPA-only VIM
--override-nonepa: removes all guest-epa parameters from all VDU. Useful to onboard EPA-based VNF packages to be deployed in a non-EPA VIM
--override-paravirt: overrides all VDU interfaces to PARAVIRT. Useful if packages are going to be deployed in a VIM that does not support SR-IOV or PCI-PASSTHROUGH interfaces.

The following video demonstrates how these options work.

10.9. Filtering requests

Some commands have the option --filter that allows to filter Read operations (*-list, *-show) to restric the output to the items matching de filter. Below an example for osm ns-list:

$ osm ns-list -h
Usage: osm ns-list [OPTIONS]

  list all NS instances

  Options:
    --filter filterExpr    Restricts the list to the NS instances matching the filter

  filterExpr consists of one or more strings formatted according to "simpleFilterExpr",
  concatenated using the "&" character:

      filterExpr := <simpleFilterExpr>["&"<simpleFilterExpr>]*
      simpleFilterExpr := <attrName>["."<attrName>]*["."<op>]"="<value>[","<value>]*
      op := "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "cont" | "ncont"
      attrName := string
      value := scalar value

  where:
    * zero or more occurrences
    ? zero or one occurrence
    [] grouping of expressions to be used with ? and *
    "" quotation marks for marking string constants
    <> name separator

  "AttrName" is the name of one attribute in the data type that defines the representation
  of the resource. The dot (".") character in "simpleFilterExpr" allows concatenation of
  <attrName> entries to filter by attributes deeper in the hierarchy of a structured document.
  "Op" stands for the comparison operator. If the expression has concatenated <attrName>
  entries, it means that the operator "op" is applied to the attribute addressed by the last
  <attrName> entry included in the concatenation. All simple filter expressions are combined
  by the "AND" logical operator. In a concatenation of <attrName> entries in a <simpleFilterExpr>,
  the rightmost "attrName" entry in a "simpleFilterExpr" is called "leaf attribute". The
  concatenation of all "attrName" entries except the leaf attribute is called the "attribute
  prefix". If an attribute referenced in an expression is an array, an object that contains a
  corresponding array shall be considered to match the expression if any of the elements in the
  array matches all expressions that have the same attribute prefix.

  Filter examples:
     --filter  admin-status=ENABLED
     --filter  nsd-ref=<NSD_NAME>
     --filter  nsd.vendor=<VENDOR>
     --filter  nsd.vendor=<VENDOR>&nsd-ref=<NSD_NAME>
     --filter  nsd.constituent-vnfd.vnfd-id-ref=<VNFD_NAME>

10.10. Debugging

Option -v can be used to debug OSM client. There are different verbosity levels:

-v: log level INFO, shows API calls
-vv: log level VERBOSE, shows API calls and content response
-vvv: log level DEBUG, shows the different methods the client is going through

The following video illustrates the log detail for each verbosity level.

10.11. Other useful options

Some commands present useful options:

--literal: shows output in YAML format. It might be deprecated in the future in favour of a new option -o OUTPUT_FORMAT.
--wait: makes the command synchronous
--long: shows more info

10.12. Aliases

The following are command aliases with identical behaviour:

For CRUD operations over NF packages, there are different command aliases. The preferred commands is nfpkg-*. The command vnfd-*might be deprecated in the future.
- nfpkg-create|vnfpkg-create|vnfd-create: creates a new NFpkg
- nfpkg-delete|vnfpkg-delete|vnfd-delete: deletes a NFpkg
- nfpkg-list|vnfpkg-list|vnfd-list: list all xNF packages (VNF, HNF, PNF)
- nfpkg-show|vnfpkg-show|vnfd-show: shows the details of a NF package
- nfpkg-update|vnfpkg-update|vnfd-update: updates a NFpkg
For CRUD operations over NS packages, there are different command aliases. The preferred commands is nspkg-*. The command nsd-*might be deprecated in the future.
- nsd-create|nspkg-create: creates a new NSD/NSpkg
- nsd-delete|nspkg-delete: deletes a NSD/NSpkg
- nsd-list|nspkg-list: list all NS packages
- nsd-show|nspkg-show: shows the details of a NS package
- nsd-update|nspkg-update: updates a NSD/NSpkg
For CRUD operations over Network Slice Templates, the following command aliases exist:
- netslice-template-create|nst-create: creates a new Network Slice Template (NST)
- netslice-template-delete|nst-delete: deletes a Network Slice Template (NST)
- netslice-template-list|nst-list: list all Network Slice Templates (NST)
- netslice-template-show|nst-show: shows the content of a Network Slice Template (NST)
- netslice-template-update|nst-update: updates a Network Slice Template (NST)
For CRUD operations over Network Slice Instances, the following command aliases exist:
- netslice-instance-create|nsi-create: creates a new Network Slice Instance
- netslice-instance-delete|nsi-delete: deletes a Network Slice Instance (NSI)
- netslice-instance-list|nsi-list: list all Network Slice Instances (NSI)
- netslice-instance-op-list|nsi-op-list: shows the history of operations over a Network Slice Instance (NSI)
- netslice-instance-op-show|nsi-op-show: shows the info of an operation over a Network Slice Instance(NSI)
- netslice-instance-show|nsi-show: shows the content of a Network Slice Instance (NSI)
For Read operations over OSM repositories, the following command aliases exist:
- nfpkg-repo-list|vnfpkg-repo-list: list all xNF from OSM repositories
- nfpkg-repo-show|vnfpkg-repo-show: shows the details of a NF package in an OSM repository
- nsd-repo-list|nspkg-list: list all NS from OSM repositories
- nsd-repo-show|nspkg-show: shows the details of a NS package in an OSM repository

10.13. Enable autocompletion

You can enable autocompletion in OSM client by creating a file osm-complete.sh in the following way:

mkdir -p $HOME/.bash_completion.d
_OSM_COMPLETE=bash_source osm > $HOME/.bash_completion.d/osm-complete.sh

Then you can add the following to your $HOME/.bashrc file:

. .bash_completion.d/osm-complete.sh

10.14. Using osmclient as a library to interact with OSM

Assuming that you have installed python-osmclient package, it’s pretty simple to write some Python code to interact with OSM.

10.14.1. Simple Python code to get the list of NS packages

from osmclient import client
from osmclient.common.exceptions import ClientException
hostname = "127.0.0.1"
myclient = client.Client(host=hostname, sol005=True)
resp = myclient.nsd.list()
print yaml.safe_dump(resp)

10.14.2. Simple Python code to get the list of VNF packages from a specific user and project

The code will print for each package a pretty table, then the full details in yaml

from osmclient import client
from osmclient.common.exceptions import ClientException
import yaml
from prettytable import PrettyTable
hostname = "127.0.0.1"
user = admin
password = admin
project = admin
kwargs = {}
if user is not None:
    kwargs['user']=user
if password is not None:
    kwargs['password']=password
if project is not None:
   kwargs['project']=project
myclient = client.Client(host=hostname, sol005=True, **kwargs)
resp = myclient.vnfd.list()
print yaml.safe_dump(resp)