...

Note
Note as of March 2024 yarnman 2.5.x is in sunset with end of life late 2024 - all new deployment should be using 2.6.x - install guide found here Yarnman Photon Powered (YM-PH) - Installation and Upgrade Guide

Table of Contents

Prerequisites

Hardware

Specification

Virtual Machines

4 vCPU
8 GB vRAM
1 x 100 GB vDisk
- latency < 20 ms (no spikes above)
- POSIX-compatible filesystem

Note
NFS datastores are not supported by the underlying yarnman database (Couchdb) and using NFS could lead to dataloss if NFS connectivity is interupted during write operations

Virtualization software

VMware vSphere ESXi 6 or higher

VMware Workstation support 12 or higher

Yarnman Deployment

1. Deploy yarnman OVA to VMware

Yarnman ova can be depoyed either using VMware OVFtool or by uploading the ova to vSphere/ESXi

...

Info

If using Ovftool to deploy

ovftool --name="<VMNAME>" --powerOn --datastore="<datastore>" --net:"nat"="<network name>" <Yarnman OVA> "<VI path >"
VI Paths
Direct ESXI "vi://<vmware username>@<ESXI IP>"
Direct ESXI with resource pool "vi://<vmware username>@<ESXI IP>/<resource Pool>"
vSphere Host "vi://<vmware username>@<vSphere>/<datacenter name/host/<Host IP or name>"
vSphere Cluster "vi://<vmware username>@<vSphere>/<datacenter name/host/<cluster name>/<Host IP or name>"

if you use a "@" or any other special characters in your username or password it must be converted to ASCI and prefixed with % e.g. test@yarnlab.io is test%40yarnlab.io

2. Using VMware Console log into Yarnman to bootstrap configuration

Default username: yarnman Password: yarnman

Set the IP address using the VMware console.
cd /opt/yarnlab/yarnman
sudo ./scripts/bootstrap.sh
1. Do you want to set a static IP? Y or N : Enter Y to set static IP
2. You will be asked to select network interface : select number adjacent to ensXX
3. enter Ip address : Enter the required IP address
4. enter netmask : to accept default press Enter, otherwise enter required netmask
5. enter gateway : enter the required gateway address
6. enter dns server1 : to accept default, press Enter, otherwise enter required DNS server address
7. You will be asked if you want to change hostname : to accept existing hostname press N otherwise, Y + enter new hostname
  At this point, network will restart
8. You will be asked if you wish to change SSH password : enter N to keep default or Y to change password
9. You will be asked if you wish to change yarnman-protected password : Enter N to keep default or Y to change the protected password
To change the password at any time SSH and run the passwd command.

It is strongly recommended to change the default password for SSH access
Update hostname if required via /etc/hosts

Deploy as a Standalone Core

Follow these steps to install the Migration Assistant as a core server. This configuration automatically sets up the server and all required services.

Log in to the Yarnman server as user yarnman using ssh client.
Change the directory by typing cd /opt/yarnlab/yarnman
Run the install script using node and sudo:
sudo node ./scripts/install-as-core-standalone.js -p <password> --couchport <couchport> --redisport <redisport> and substitute the <value>
sudo node ./scripts/install-as-core-standalone.js -p <password> --couchport 5984 --redisport 6379

Note: If copying sample line above, ensure that <password> is replaced with

...

an appropriate database password to be used for the installation
On completion of installation from step 3, Open10 Web Browser, browse to Yarnman IP and set the administrator account password.
Accept the End User License Agreement by selecting the check box.
Under the Set Administrator Password option, enter the password that is used later to log in to the GUI & click "Save Acceptance and Update Administrator".
Image Modified
Login with the username of the administrator and password that you created.

It is strongly recommended to change the default password for web access this is done by going into the default access policy then users

Install As Arm

Note
This is only required for distributed yarnman deployments where network traversal is required

Only follow these steps if you are deploying Yarnman as a distributed system (multiple VMs)
Note that configuration is required on the core node for allowing connectivity from the Arm to the Core describe in the LOCAL FIREWALL CONFIGURATION section in this document.https://yarnlab.atlassian.net/wiki/spaces/YSP/pages/2730393636/Yarnman+Administration#Local-Firewall-Configuration
This will install the OVA as a node of Yarnman, connect to the central core database and enroll. Once accepted by the core services, interfaces may be added to it
Target full path of the core's Redis - redis://<some host or ipaddress>:<port - likely 6378>

CD to /opt/yarnlab/yarnman/
Run the script using node and sudo:

sudo node ./scripts/install-as-arm.js -n <node name> -c <couchpath> -r <redispath>

with values prepared above substituted for <value>.

Node name to appear on the enrollment screen in AdminApp of the core.
Target full path of the core's CouchDB - http(s)://<some host or ipaddress>:<port - likely 5984>

sudo node ./scripts/install-as-arm.js -n <name> -c http://<core ip>:5984 -r redis://<core ip>:6379'

Go to the Core's Administration App → Enrollments and accept the new node, you may add services and interface in the normal way.
The enrollment process will auto-generate credentials for the Arm.

Setup NTP Synchronization

By default time is synchronized from the virtual host, for distributed deployments it is recommended to setup NTP on both the core and arm nodes

Edit the following file and setting NTP server required replacing 1.2.3.4
Code Block
sudo nano /etc/systemd/timesyncd.conf NTP=1.2.3.4

Restart time service

Code Block
sudo systemctl restart systemd-timesyncd.

...

Installing Yarnman onto Ubuntu docker image on M1 Mac:

Install Docker
Set Maximum Memory Size to at least 4GB in Docker Resource configurations
Start up Ubuntu container: docker run -v ~/code:/mnt/code -it --network host --name yarnman_ubuntu --platform linux/amd64 ubuntu:bionic /bin/bash
Install necessary packages in the container:

Code Block

apt-get clean && apt-get update

DEBIAN_FRONTEND=noninteractive apt-get install -y curl build-essential git software-properties-common apt-offline open-vm-tools jq apt-transport-https debconf-utils sudo cmake curl libcap2-bin npm

add-apt-repository ppa:jonathonf/ffmpeg-3apt-get update

DEBIAN_FRONTEND=noninteractive apt-get install -y python2.7 openjdk-8-jdk nodejs haproxy unzip ffmpeg traceroute apt-offline openssh-server cryptsetup build-essential libssl-dev libreadline-dev zlib1g-dev linux-source dkms nfs-common apt-offline software-properties-common ca-certificates

5. Generate SSH keys on the container and add them to Bitbucket:

Code Block
ssh-keygen eval $(ssh-agent) ssh-add ~/.ssh/id_rsa cat ~/.ssh/id_rsa.pub

Copy the key into Bitbucket

6. Create yarnman admin user and directories:

Code Block
useradd yarnman usermod -aG sudo yarnman mkdir -p /var/log/yarnman mkdir -p /opt/yarnlab/yarnman visudo # (set NOPASSWD:ALL) for everything su - yarnman

7. Install node, clone secundus repository into /mnt/code, and build Yarnman:

Code Block
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh \| bash nvm install v12.18.3 cd /mnt/code git clone git@bitbucket.org:yarnlab/secundus.git cd secundus npm install npm run build

8. Install Yarnman as standalone:

Code Block
sudo node ./scripts/install-as-core-standalone.js -b -p admin -r 6379 -c 5984

service

Verify time is correct after 5 minutes

Code Block
yarnman@yarnman-arm:~$ timedatectl status Local time: Wed 2021-06-16 13:13:10 UTC Universal time: Wed 2021-06-16 13:13:10 UTC RTC time: Wed 2021-06-16 13:13:10 Time zone: Etc/UTC (UTC, +0000)

Yarnman 2.5.x administration

Yarnman Management/ Utilities/ Specifications

Yarnman Manual Log Collection

If log collection option as described in previous chapters is not available/ can not be accessed, log collection may be performed manually by ssh access to Yarnman
Please send screenshot of error encountered and detailed steps to reproduce and time stamp from ssh via date command
run command via ssh to collect logs
tar -czvf yarnman-logs.tar.gz --exclude='*.tar.gz' /var/log/yarnman
Then sftp file and send to support as required

Yarnman database log collection

If requested by support this log collection may be required

run command via ssh to collect logs
tar -czvf yarnman-logs-db.tar.gz --exclude='*.tar.gz' /var/log/couchdb/couchdb.log /var/log/couchdb/couchdb.log.1

Then sftp file and send to support as required

Yarnman increase disk space for database

To increase the storage space for any of the log or database filesytems in Yarnman.

Info
Please contact support if you have any queries on appropriate disk space

2.5.X process

Log in to Yarnman using ssh
Type df which will show you the size of the filesystems. Note the space in var/lib/couchdb. If this is more than 50% used it is recommended to increase space so that less than 50% of the filesystem is used

...

Log in to vCentre and select the VM in question.
If there are any snapshots, these must be removed before increasing the storage for VM (a new snapshot can be performed after increasing disk space)
Increase the disk space - generally, the default diskspace allocated for Yarnman is 100G, increase the required diskspace to ensure that the /var/lib/couchdb partitionwill be less than 50% used
Once the storage space on the VM has been increase - log back into Yarnman using ssh
To increase the storage space for the couchdb partition, using all of the increased VM storage, type sudo ./scripts/resize-disk.sh var-lib-couchdb
Verify that filesystem storage is now OK
To further reduce storage space, it is recommended to compact couchdb as per below process

Yarnman database compaction

From time to time - particularly before/ after migrating very large CUCM clusters using Wrangler or when multiple discoveries are run, it is prudent to compact the couchdb database

Warning
Do not run a database compaction when there is less that 30% disk space available, increase disk space before as the compaction process does temporarily consume additional

In 2.5.x

Log in to Yarnman using ssh
Type cd /opt/yarnlab/yarnman
type sudo node ./scripts/compactdb.js

Upgrade Yarnman - Apply a patch

Note
Take a VMware snapshot before applying patch

Process to apply patch in Yarnman

Copy the patch file: yarnman-app-<version>.tar.gz.sig to /opt/yarnlab/install via SFTP
ssh into the server
Run command: cd /opt/yarnlab/yarnman
Run the upgrade script: ./scripts/install-yarnman-app.sh yarnman-app-<version>.tar.gz.sig

Info

If you are supplied an unsigned patch that does not have .sig suffix step 4 is replaced with

./scripts/install-yarnman-app.sh yarnman-app-<version>.tar.gz -i

There will also be an error Package is not signed use --ignore-verification

Upgrade Yarnman – Linux Deps upgrade

Note
Take a VMware snapshot before applying deps upgrade

Process to upgrade the Linux Deps. It is recommended to take a snapshot prior to update

Copy the update file: yarnman-linux-bundle-master-<version>.tar.gz.sig to /opt/yarnlab/install via SFTP
ssh into the server
Run command: cd /opt/yarnlab/yarnman
Run the upgrade script: ./scripts/ install-linux-deps.sh yarnman-linux-bundle-master-<version>.tar.gz.sig

Note that all download links all have a corresponding .md5 and linux-deps upgrade also have optional md5 verification

Upgrade Yarnman – Linux Version 18 upgrade

Process to upgrade Linux to version 18. It is strongly recommended to take a snapshot prior to upgrade

Download Linux Upgrade Script + Application Patch from Yarnlab web site

https://yldev.blob.core.windows.net/packages/yarnman-linux-upgrade18-bundle-<Ver>-master-<Build>.tar.gz.sig

https://yldev.blob.core.windows.net/packages/yarnman-app-<Ver>-master-<Build>.tar.gz.sig

SFTP file on to yarnman server - place in install directory /opt/yarnlab/install
Take a Snapshot
ssh to yarnman server

CD /opt/yarnlab/yarnman

Run The application patch

./scripts/install-yarnman-app.sh yarnman-app-<Ver>-master-<Build>.tar.gz.sig

Note: this command may require -i at the end depending on source version. It would then be ./scripts/....tar.gz -i

Verify that app installed correctly in Yarnman Administration App Web GUI
Run the OS upgrade file from ssh directory /opt/yarnlab/yarnman

sudo ./scripts/upgrade-baseos18.sh yarnman-linux-upgrade18-bundle-<Ver>-master-<Build>.tar.gz.sig

Note: this command may require -i at the end depending on source version. It would then be ./scripts/....tar.gz -i

During the upgrade you will be prompted if you want to run a backup - select Y to perform backup
On completion - Y to reboot

Local Firewall Configuration

Default local firewall rules

Code Block
sudo ufw allow ssh sudo ufw allow http sudo ufw allow http ssudo ufw enable

Additional rules are required on the core node for each arm deployed

Code Block
sudo ufw allow from <ip address of arm> to any proto tcp port 5984,5986 udo ufw allow from <ip address of arm> to any proto tcp port 6379,6380

Default Terminator Configuration (Testmate)

Code Block
sudo ufw allow from any proto udp port 6700:6799

Yarnman SSL Certificates

Configuring Intermediate Certificates

Typical format for standard SSL.

/opt/yarnlab/yarnman/config

ssl-cert.cert - Standard certificate sent to clients

ssl-key.pem - Private key file for checking response

In order to enable intermediate certificates we must create new folder in /config.

Code Block
~/config /ca 1-name.crt 2-name.crt 3-name.crt

The /ca folder contains the intermediate certificates that will be loaded in order. The easiest way to achieve this is to use the naming conventions 1-, 2- etc. Each certificate must end in .crt in order to be loaded.

Once the folder is created and at least one certificate is added in the format indicated the services on the node must be restarted.

Generate CSR

To acquire a new certificate you must generate a CSR (Certificate Signing Request). This may be done initially after creating private key or when a certificate expires
Certificate Locations /opt/yarnlab/yarnman/config
ssl-cert.cert - Standard certificate sent to clients
ssl-key.pem - Private key file for checking response
Open ssh session to server – go to /opt/yarnlab/yarnman/config

To generate CSR

Open Editor 'nano cert.cnf'
In the editor – complete following info

Code Block


[req]
distinguished_name  = req_distinguished_name
req_extensions = v3_req
[ req_distinguished_name ]
emailAddress      = Email Address (emailAddress_max    = 64)
[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names (Recommend using DNS name here)
[alt_names]
DNS.1 = <DNS name>

Image Added

Backup and Restore

Backup Yarnman

Open SSH session

Run command: cd /opt/yarnlab/yarnman

Run the backup script: ./scripts/backup-yarnman.sh -b

Backup script will create Backup Directory /opt/yarnlab/backup and create backup file

Restoring Backup

Open SSH session

Ensure that the backup directory /opt/yarnlab/backup exists with backup file

Run command: cd /opt/yarnlab/yarnman

Run the restore script: ./scripts/backup-yarnman.sh -r

The backup script will identify the latest backup in the backup directory and restore from there

...

Wrangler 2.5.X Setup

Wrangler UCMC will require two services described below

Wrangler OPA App
Interconnect Service

From Top right corner of display drop down +Add Service, select Wrangler OPA Migration App

...

Define Service Name, select Yarnman Node, Select UCM Migration Assistant Migration, select required Authentication policy from drop down, then Submit

...

Select Services from Menu → Select either Proxy Service or Standalone Proxy Service depending on which proxy service is present by default (Do not add a new proxy service unless specifically required)

...

From Proxy Configuration Page, select ‘Service Routing’ from top right corner

...

Select ‘Add Yarnapp' and from the drop down, select the Wrangler Migration App ->Submit

...

The Wrangler UCMC app has now been added and may be selected from top Right Drop down

...

Set up Interconnect Service

Select Services from Menu, then + Add Service, from drop down select Interconnect Service

Image Added

Populate Service Name Field, select node from Node / Arm field drop down, then select Submit

...

Versions Compared

Old Version 39

New Version Current

Key

Prerequisites