Cisco Software Manager Server 4.

0
System Administration Guide

Version 1.0
Table of Contents
INTRODUCTION ................................................................................................................................................ 3
CHECKING THE CSM CONTAINER STATUS ......................................................................................................... 3
CHECKING THE CSM SUPERVISOR SERVICE STATUS .......................................................................................... 3
CSM SUPERVISOR CONTAINER API ................................................................................................................... 4
RESTARTING THE CSM SERVER CONTAINER ...................................................................................................... 5
STOPPING THE CSM SERVER CONTAINER ......................................................................................................... 5
STARTING THE CSM SERVER CONTAINER .......................................................................................................... 6
CSM SERVER BASIC CONFIGURATION ............................................................................................................... 6
CHANGING THE DEFAULT WEB FRONTEND PORT......................................................................................................... 7
ENABLING SSL.................................................................................................................................................. 7
MOUNTING LOCAL FOLDERS FOR CSM SERVER ......................................................................................................... 8
CONFIGURING PROXY ....................................................................................................................................... 9
CHECKING THE SYSTEM LOGS ......................................................................................................................... 10
CSM SERVER OFFLINE UPGRADE STEPS........................................................................................................... 10
1. STOP THE CSM-SUPERVISOR SERVICE ........................................................................................................... 10
2. STOP AND REMOVE ALL CSM DOCKER CONTAINERS ....................................................................................... 11
3. REMOVE CSM DOCKER IMAGES ................................................................................................................ 11
4. COPY THE NEW CSM PACKAGE TO THE LINUX HOST AND EXTRACT THE CONTENT .................................................. 11
5. LOAD NEW CSM DOCKER IMAGES ............................................................................................................. 12
6. COPY NEW JOSN CONFIGURATION FILES INTO PROPER LOCATIONS .................................................................... 12
7. RESTART THE CSM-SUPERVISOR SERVICE ...................................................................................................... 12
Introduction
This document provides description of basic administration operation for Cisco Software
Manager Server 4.0. The CSM 4.0 is a web-based application running in Docker
environment. The overall CSM application consists of three major components:
• CSM Supervisor
• CSM Database
• CSM Server

The installation script, described in the Installation Guide, also installs the systemd service
instantiating the CSM Supervisor docker container.

The CSM Supervisor container is required to maintain the other containers, restart them,
upgrade, and change the configuration. For the rest of the document it is assumed that CSM
Supervisor container is up and running,

Checking the CSM Container Status

During the normal operation three docker containers should be active and running:

$ docker ps
CONTAINER ID IMAGE COMMAND CREATED
STATUS PORTS NAMES
0785f0511ce7 containers.cisco.com/spnscsm/qemux86-64-csm-server "/bin/entry.sh run.sh" 43 minutes
ago Up 43 minutes csm-server
36f30ef7fd2a containers.cisco.com/spnscsm/amd64-csm-supervisor "python3 -m csmcloud" 21 hours
ago Up 4 seconds csm-supervisor
01066d2795e5 containers.cisco.com/spnscsm/amd64-csm-db "/usr/bin/entry.sh" 5 days ago
Up 3 hours csm-database
$

Checking the CSM Supervisor Service Status

To check the current CSM Supervisor service status the following command can be executed
on the server host:

$ $ systemctl is-active csm-supervisor.service

active
$

$ systemctl status csm-supervisor.servicde

● csm-supervisor.service - CSM Cloud Server Supervisor
Loaded: loaded (/etc/systemd/system/csm-supervisor.service; enabled; vendor preset:
enabled)
Active: active (running) since Sun 2018-12-16 23:15:36 PST; 21h ago
Process: 26232 ExecStop=/usr/bin/docker stop csm-supervisor (code=exited,
status=0/SUCCESS)
Process: 26309 ExecStartPre=/usr/bin/docker stop csm-supervisor (code=exited,
status=0/SUCCESS)
Main PID: 26316 (csm-start)
Memory: 5.6M
CPU: 3.668s
CGroup: /system.slice/csm-supervisor.service
├─26316 /bin/bash /usr/bin/csm-start
└─26358 docker run --name csm-supervisor
$
The supervisor service requires docker.service running by the systemd which should have
been enabled during initial CSM installation. The service will be restarted automatically after
10 seconds if it detects there was a crash.

$ systemctl is-enabled csm-supervisor.service

enabled
$

To stop the CSM Supervisor service

$ sudo systemctl stop csm-supervisor.service

$ docker ps
CONTAINER ID IMAGE COMMAND
CREATED STATUS PORTS NAMES
0785f0511ce7 containers.cisco.com/spnscsm/qemux86-64-csm-server "/bin/entry.sh
run.sh" 5 hours ago Up 5 hours csm-server
01066d2795e5 containers.cisco.com/spnscsm/amd64-csm-db
"/usr/bin/entry.sh" 5 days ago Up 7 hours csm-
database
$

The CSM Supervisor container is not running however CSM Server and CSM Database
containers are still operating. This is intended and allows upgrading the CSM Supervisor
without interrupting the CSM Server functionality.

To start CSM Supervisor service:

$ sudo systemctl start csm-supervisor.service

$
$ docker ps
CONTAINER ID IMAGE COMMAND
CREATED STATUS PORTS NAMES
0785f0511ce7 containers.cisco.com/spnscsm/qemux86-64-csm-server "/bin/entry.sh
run.sh" 5 hours ago Up 5 hours csm-server
36f30ef7fd2a containers.cisco.com/spnscsm/amd64-csm-supervisor "python3 -m
csmcloud" 25 hours ago Up 19 seconds csm-supervisor
01066d2795e5 containers.cisco.com/spnscsm/amd64-csm-db
"/usr/bin/entry.sh" 5 days ago Up 7 hours csm-
database
$

It is known that CSM Supervisor service does not automatically restart by systemd after
Docker is updated. According to Docker docs (https://docs.docker.com/config/containers/live-
restore/), By default, when the Docker daemon terminates, it shuts down running containers.
When this occurs, please manually start the CSM Supervisor service which will restart the
other containers such as CSM Server and CSM Database.

CSM Supervisor Container API

The CSM Supervisor container provides the interface to control the whole CSM solution
through the REST API. The following chapters show several examples of how to use that
API. The CSM Supervisor container REST endpoint is accessible only from the host server at
the static internal IP address: 172.33.32.2.
The REST calls can be executed using any curl or wget and in below examples it is also
assumed that jq utility is installed on the server. The jq utility is used only to better format the
JSON output of REST calls and can be omitted in below examples.

If you use the HTTP proxy, make sure that no_proxy environment variable also contains
172.33.32.2 IP address, otherwise the Supervisor API will not be reachable.

$ export no_proxy=$no_proxy,172.33.32.2

Restarting the CSM Server container

In some cases the CSM Server container must be restarted. For example, when the
configuration change is applied. This can be done by issuing the following command:

$ curl -sXPOST http://172.33.32.2/csm/restart | jq

{
"result": "ok",
"data": {}
}
$

Now the status shows that the csm-server container is up for few seconds which mean has
been recently restarted:

$ docker ps
CONTAINER ID IMAGE COMMAND
CREATED STATUS PORTS NAMES
0f2314ab0357 containers.cisco.com/spnscsm/qemux86-64-csm-server "/bin/entry.sh
run.sh" 2 seconds ago Up 1 second csm-server
36f30ef7fd2a containers.cisco.com/spnscsm/amd64-csm-supervisor "python3 -m
csmcloud" 26 hours ago Up 18 minutes csm-supervisor
01066d2795e5 containers.cisco.com/spnscsm/amd64-csm-db
"/usr/bin/entry.sh" 5 days ago Up 7 hours csm-
database
$

Please make sure there are no pending installation jobs before restarting the CSM Server
container.

Stopping the CSM Server container

To stop the CSM Server container the following command can be issues:

$ curl -sXPOST http://172.33.32.2/csm/stop | jq

{
"result": "ok",
"data": {}
}
$
$ docker ps
CONTAINER ID IMAGE COMMAND
CREATED STATUS PORTS NAMES
36f30ef7fd2a containers.cisco.com/spnscsm/amd64-csm-supervisor "python3 -m
csmcloud" 26 hours ago Up 19 minutes csm-supervisor
01066d2795e5 containers.cisco.com/spnscsm/amd64-csm-db "/usr/bin/entry.sh"
5 days ago Up 7 hours csm-database
$

Right now the web application is not running.

Starting the CSM Server container

In normal situation it is never required to start or stop the container, however if the container
was stopped previously it can be started again with the following command:

$ curl -sXPOST http://172.33.32.2/csm/start | jq

{
"result": "ok",
"data": {}
}
$ docker ps
CONTAINER ID IMAGE COMMAND
CREATED STATUS PORTS NAMES
b40d065947e4 containers.cisco.com/spnscsm/qemux86-64-csm-server "/bin/entry.sh
run.sh" 5 seconds ago Up 4 seconds csm-server
36f30ef7fd2a containers.cisco.com/spnscsm/amd64-csm-supervisor "python3 -m
csmcloud" 26 hours ago Up 30 minutes csm-supervisor
01066d2795e5 containers.cisco.com/spnscsm/amd64-csm-db
"/usr/bin/entry.sh" 5 days ago Up 8 hours csm-
database
$

CSM Server Basic Configuration

The CSM Configuration can be displayed by issuing the REST call from host server to the
special endpoint which is reachable only from the server:

$ curl -s http://172.33.32.2/csm/info | jq
{
"result": "ok",
"data": {
"version": "4.0.0-dev.56",
"last_version": "4.0.0-dev.56",
"machine": "qemux86-64",
"image": "containers.cisco.com/spnscsm/qemux86-64-csm-server",
"custom": false,
"boot": true,
"port": 5000,
"ssl": false,
"watchdog": true,
"wait_boot": 120,
"in_progress": false,
"volumes": {}
}
}
$

This output shows the current CSM Server container version and last available version for
upgrade. Moreover, there is information about several configuration options that can be
changed.
Changing the default web frontend port

Administrator can change the default port for the web frontend port by issuing the following
command:

$ curl -sXPOST http://172.33.32.2/csm/options -d '{"port":5001}' | jq

{
"result": "ok",
"data": {}
}
$

To verify the change issue:

$ curl -s http://172.33.32.2/csm/info | jq
{
"result": "ok",
"data": {
"version": "4.0.0-dev.56",
"last_version": "4.0.0-dev.56",
"machine": "qemux86-64",
"image": "containers.cisco.com/spnscsm/qemux86-64-csm-server",
"custom": false,
"boot": true,
"port": 5001,
"ssl": false,
"watchdog": true,
"wait_boot": 120,
"in_progress": false
}
}
$

The port configuration is changed to 5001 and then the CSM Server container must restarted
(see earlier in the document how to restart CSM Server container with REST API) to apply
this change.

Enabling SSL

To be able to use the SSL certificate two files must be uploaded to the /usr/share/csm/ssl
directory on the host server:

certificate.pem
key.pem

Please make sure that the exact filenames are used for the certificate and private key.
Then the CSM Server container must be reconfigured to use SSL certificate for web frontend.

$ curl -sXPOST http://172.33.32.2/csm/options -d '{"ssl":true}' | jq

{
"result": "ok",
"data": {}
}
$ curl -s http://172.33.32.2/csm/info | jq
{
"result": "ok",
 "data": {
"version": "4.0.0-dev.56",
"last_version": "4.0.0-dev.56",
"machine": "qemux86-64",
"image": "containers.cisco.com/spnscsm/qemux86-64-csm-server",
"custom": false,
"boot": true,
"port": 5000,
"ssl": true,
"watchdog": true,
"wait_boot": 120,
"in_progress": false
}
}
$

The last step is to restart the CSM Server container using REST API (see earlier in the
document how to restart CSM Server container).

Mounting local folders for CSM Server

In some cases, specific host local folders should be accessible by the CSM Server. For
example, the TFTP repository may be mounted on the host server using any network file
system, i.e. NFS) and used by the TFTP local repository to allow the user to browse the
packages.

Let’s assume the local directory on the host is /mnt/tftp and it should be accessible inside the
CSM Server container with the same path.

To check the current configuration run:

$ curl -s http://172.33.32.2/csm/info | jq
{
"result": "ok",
"data": {
"version": "4.0.0",
"last_version": "4.0.0",
"machine": "qemux86-64",
"image": "devhub-docker.cisco.com/csm-docker/qemux86-64-csm-server",
"custom": false,
"boot": true,
"port": 5000,
"ssl": false,
"watchdog": true,
"wait_boot": 120,
"in_progress": false,
"volumes": {}
}
}

The volumes key has empty dictionary value which means there are no local folders mounted.

To make the local /mnt/tftp path accessible by the CSM Server the following command must
be issues:

$ curl -sX POST http://172.33.32.2/csm/options \

-d '{"volumes":{"/mnt/tftp": {"bind":"/tftp"}}}' | jq
{
"result": "ok",
"data": {}
}
$

To check if the settings are applied run:

$ curl -s http://172.33.32.2/csm/info | jq '.data.volumes'

{
"/mnt/tftp": {
"bind": "/tftp"
}
}

Now it is required to restart the CSM Server container.

$ curl -sXPOST http://172.33.32.2/csm/restart | jq

{
"result": "ok",
"data": {}
}
$

To check if the volume is mounted inside the container issue:

$ docker inspect csm-server | jq '.[0].Mounts[] | select(.Source == "/mnt/tftp")'

{
"Type": "bind",
"Source": "mnt/tftp",
"Destination": "/tftp",
"Mode": "rw",
"RW": true,
"Propagation": "rprivate"
}
$

Configuring PROXY

CSM Server requires Internet connection to be able to download the information about latest
packages and SMUs and the information about the latest version available for self-upgrade.
For the servers located behind the corporate proxy the HTTPS proxy setting is needed.

If the CSM Server was installed from the installation script in the Installation Guide there is
detailed description on how to setup a Proxy.

It is assumed that Docker daemon proxy is already configured. If the configuration is

required, please refer to the Docker Guide: https://docs.docker.com/config/daemon/systemd/
how to setup proxy for Docker daemon.

The proxy configuration can be added to the /etc/csm.json file below:

$ cat /etc/csm.json
{
"api_key": "AKCp5bBCwQFwXvfnC83HVsJVM77qedNm5m9bSsMGjhEVVFxtzjFuJa4us8ji6R8FUJF99yMrK",
 "api_user": "csmserver.gen",
"csm_registry": "https://devhub-docker.cisco.com",
"supervisor": "devhub-docker.cisco.com/csm-docker/amd64-csm-supervisor",
"server": "devhub-docker.cisco.com/csm-docker/qemux86-64-csm-server",
"database": "devhub-docker.cisco.com/csm-docker/amd64-csm-db",
"channel": "stable",
"data": "/usr/share/csm"
}
$

To setup or change the proxy settings for CSM Server edit this file and add/modify the
following keys:

"https_proxy": "<your proxy url>",

"http_proxy": "<your proxy url>",
"no_proxy": "<ip or domains, comma separated>",

After adding/modifying those keys the existing containers should be removed and CSM
Server restarted.

$ sudo systemctl stop csm-supervisor.service

$ docker stop csm-server
$ docker rm csm-server
$ docker rm csm-supervisor
$ sudo systemctl start csm-supervisor.service

Checking the System Logs

In case of problems it may be useful to collect the container logs. The CSM Server consists
of three containers: csm-supervisor, csm-server and csm-database

To collect the logs, type:

$ docker logs csm-supervisor

$ docker logs csm-server

$ docker logs csm-database

Please collect those logs before contacting cs-software-manager@cisco.com for support.

CSM Server Offline Upgrade Steps

When a new release becomes available, by default CSM Server can easily be upgraded by
clicking on the upgrade icon on Web GUI. In case CSM Server has no internet access, manual
steps are required to upgrade CSM Server. The details are given as follows with an example
of upgrading CSM from version 4.0.2 to 4.0.3. We begin by assuming that CSM version 4.0.2
is up and running.

1. Stop the csm-supervisor Service

Please first stop the csm-supervisor service.

cisco@netbrain:~$ sudo systemctl stop csm-supervisor

2. Stop and Remove All CSM Docker Containers

cisco@netbrain:~$ docker ps -a | grep csm | awk '{print $1}' | xargs docker stop
b3f9fc0cb959
e7b08dc7ba80
7a2021f47379

cisco@netbrain:~/4.0.3$ docker ps -a | grep csm | awk '{print $1}' | xargs sudo docker rm
b3f9fc0cb959
e7b08dc7ba80
7a2021f47379

3. Remove CSM Docker Images

cisco@netbrain:~/4.0.3$ docker images -a | grep csm | awk '{print $3}' | \

> awk '!NF || !seen[$0]++' | xargs sudo docker image rm -f
Untagged: devhub-docker.cisco.com/csm-docker/qemux86-64-csm-server:4.0.2
Deleted: sha256:0b81bcd11431e57b2837db3582a4690068bd2007016f58b55313b68ed6d935aa
Deleted: sha256:bdd2b5bf6fd371769c43e7d7b5616ce94048c7b887c5edc4370b7c8e0c41ab26
Deleted: sha256:51913508c2388d607ec96624b2fd99f28075d5fb319f69591770c808bc6c0f93
Deleted: sha256:2bc4815cf7cf6ad5a0b53d8c0f027e8575660e8f1d7dbcd78c43bed517475170
Deleted: sha256:b4677ddfdebe8e9867aa03adb44c786405a40d5bc72088f9c555bcaf0b623bb6
Deleted: sha256:fa861aebda14da8540ffded2dcfc1fc9f9ec200dc68e6e69638e2e3651de2765
Deleted: sha256:3bb2d32c1a99491bf7ca612d9524da510372ecee6db61fb65c03d2fd2fa26561
Deleted: sha256:70dd16d93b2fd59695425c6e9cefe0fb1c08899f388adf5fab2897a277c5d842
Deleted: sha256:93c6d24077e9ce809d71614dd6a31ff5f023d76505750f8929bc604ec649569b
Deleted: sha256:9c8b0f60581a493d031d8f23537b837d6390945e5655bd42b737e5beb660abaa
Deleted: sha256:ad73b1a52199df09ae8a10e094756511c1a955adf9d5bfa8399927c23134fa1b
Deleted: sha256:8f99d767effa4c44fe3f9eba28bb5eab965e73446b85e59669097a88c5ed98b1
Deleted: sha256:55309cbd9d30100c4b1876a1348cd80a3ac7b15b46b1f14006cc2fad27bb121b
Deleted: sha256:f20891dc522af605dac049007ff373c526238fbf0ae5906822895b35064b00b0
Untagged: devhub-docker.cisco.com/csm-docker/amd64-csm-supervisor:20
Deleted: sha256:18de8cc1f2cf09abeb8efadd65737a7259420f7725ed87500d275da087ee2692
Deleted: sha256:7bde52732bd5c62ea52d2011c70f0d4a01057213fbc7da15e699b39ef3741e44
Deleted: sha256:abf5858f06835e8737bdd006f8ea119348ea8402f3d097de1cc7ef2d02e1ce4a
Deleted: sha256:65daa7d4b37ae90f8c94f20e9eae5fbfa0639fadbade553ed08da57bce7c44c7
Deleted: sha256:efbffaa34cecba186119f82237d22d1d761d9ea41a2c9de0aafdf3c5503858d1
Deleted: sha256:56b2bb1d5263baff30f91c46f0cff1cd2350d4a6b2816c188b81fb2080e187e5
Deleted: sha256:957dcb9cb055f64e69d399e031d6717d2990b1d990d4d92054f321168f0d0916
Deleted: sha256:27d2bee6340617f4cb4f467c847d80fd8c3a286727bb5a375542cb1ad781fd5f
Deleted: sha256:b7d9f24514d63feaaf2e778b5ceebe169bdbd73d7765018f3a7b854c46ad00f8
Deleted: sha256:57f169a55e0bdacf3523dfcfd670ca6a331ff84010f62d5fb6735c035c216121
Deleted: sha256:d87f52fcb05d6f7e55188ceaecc1672850f33f86687ac9b44dc55be974fb4bac
Deleted: sha256:ddb498cd09d2a18ec4b9f7c01ebcead9866d47c665d128d121dc03c8164087e2
Untagged: devhub-docker.cisco.com/csm-docker/amd64-csm-db:1
Deleted: sha256:08ae3cd268159bdd555e0061500dabf8a101d91ee30cc57e74780bac101fe319
Deleted: sha256:c2bea5ae5b9320f8eec5627c89cfc0f339fd56532a6d4d13f2972d128ff00114
Deleted: sha256:fe8cdee1c38ff87a704316a6ff44e09c10bf07777b84edee719bf9c4025f236e
Deleted: sha256:25dd919da1cfed4323260620197e05328ffbab489791da1e5c0d7eead2a1725e
Deleted: sha256:5f3b251513ed92b291b922b2056e4ab7f451ffaada1a81ed7e02f77682692576
Deleted: sha256:df64d3292fd6194b7865d7326af5255db6d81e9df29f48adde61a918fbd8c332

4. Copy the New CSM Package to the Linux Host and Extract the Content

Please copy the new CSM tar file to the Linux host with a USB stick or other methods. For
example,

cisco@netbrain:~$ ls -tl csm403.tar

-rw-r--r-- 1 cisco cisco 651141120 Feb 28 23:20 csm403.tar

Please extract the content from the tar file.

cisco@netbrain:~$ tar -xvf csm403.tar

4.0.3/
4.0.3/updater.json
4.0.3/csm.json
4.0.3/amd64-csm-db.docker
4.0.3/amd64-csm-supervisor.docker
4.0.3/qemux86-64-csm-server.docker

Please step into the sub-directory and locate all the new Docker images and JSON
configuration files.

cisco@netbrain:~$ cd 4.0.3
cisco@netbrain:~/4.0.3$ ls -tl
total 635892
-rw-r--r-- 1 cisco cisco 88 Feb 28 23:07 updater.json
-rw-r--r-- 1 cisco cisco 562 Feb 28 23:07 csm.json
-rw------- 1 cisco cisco 169412096 Feb 28 22:28 amd64-csm-db.docker
-rw------- 1 cisco cisco 187491328 Feb 28 22:18 amd64-csm-supervisor.docker
-rw------- 1 cisco cisco 294225408 Feb 28 22:13 qemux86-64-csm-server.docker

5. Load New CSM Docker Images

cisco@netbrain:~/4.0.3$ l=`ls *.docker`; for f in $l; do sudo docker load < $f; done
Loaded image: devhub-docker.cisco.com/csm-docker/amd64-csm-db:1
Loaded image: devhub-docker.cisco.com/csm-docker/amd64-csm-db:latest
Loaded image: devhub-docker.cisco.com/csm-docker/amd64-csm-supervisor:20
Loaded image: devhub-docker.cisco.com/csm-docker/amd64-csm-supervisor:latest
Loaded image: devhub-docker.cisco.com/csm-docker/qemux86-64-csm-server:4.0.3
Loaded image: devhub-docker.cisco.com/csm-docker/qemux86-64-csm-server:latest

6. Copy New JOSN Configuration Files into Proper Locations

cisco@netbrain:~/4.0.3$ sudo cp csm.json /etc/csm.json

cisco@netbrain:~/4.0.3$ sudo cp updater.json /usr/share/csm/updater.json

7. Restart the csm-supervisor Service

cisco@netbrain:~/4.0.3$ sudo systemctl restart csm-supervisor

Please email cs-software-manager@cisco.com for questions.