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 

OVA file format yarnman-2.X.X-master-XXXXXX.ova

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
  8. You will be asked if you wish to change 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.

1. Log in to the Yarnman server as user yarnman using ssh.
2. Change the directory to /opt/yarnlab/yarnman/
3. 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
4. Browse to Yarnman IP and set the administrator account password.
5. Accept the End User License Agreement by selecting the check box.
6. 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".
7. 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

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.
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>

1. CD to /opt/yarnlab/yarnman/
2. 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'

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

Yarnman Administration

Logging in to Yarnman administration,  https://<ip address or DNS name>/administration

Enter Username and Password to log in

Nodes

The Nodes option provides a view of deployed core node arm and any remote arms deployed.
Select 'Nodes' on the left side menu. The following screen will open:

This will give visibility of all created nodes.

Note: More results and in order to see all the created services in excel format, just click on "Download Results" – a file will be downloaded, that may be opened in Excel.

Nodes may be filtered by the filter of field Name, Customer, Type, Version, Build, IPAddress, Hostname, External Address, IP Source Connected, Uptime and Status. In order to do so, click on the corresponding arrow right next to the field name and select the appropriate choice.
In order to see the corresponding node, click on the nodes name itself. The following screen will open:

There are now several options to change details for, and to view the current settings of the node, such as Unique ID, Name, Associated Customer, IP Address, Media/Control Port Start Port Range, Media/Control Port End Port Range, Hostname and Administrative Node.

Since every node / arm has the Jade Berlin JTAPI service installed (which is required for the Yarnlab Testmate App), these may be restarted and (re-) downloaded from here. To (re-) download it, you will be asked to enter the corresponding IP of the CUCM to download the jar file from.

To ask the system to display the disk usage here. Press "Show Disk Usage" and the following details will display:

Pressing "Submit" to confirm the changes;or
Pressing "Delete Node" will delete the node completely and return to the first Node Overview screen.

To display additional details, select the "Interfaces" or "Ports" tab, which will take you directly to the corresponding interfaces, ports and their details.

Services

The Services Option allows for the view/ addition/ alteration of services and applications attached to deployed Yarnman nodes
Click on 'Services' on the left side menu. The following screen will open:

This will display existing services.
Note: More results and in order to see all the created services in excel format, just select "Download Results" – a file will be downloaded that may be opened in Excel.
Services may be filtered by Services, Node and Customer. They can also be filtered by the condition of field Name, Type, Node, Ports, Customer and Status. In order to do this, select the corresponding arrow right next to the field name and select your choice.
Alternatively , a service name may be entered in the search field to search for it directly.
In order to see the corresponding Service, the service name itself may be selected which will display the following screen:

This displays the existing settings / details for this service, such as the Unique ID, the Service Name and the corresponding Node / Arm, these may be changed as required.
Pressing "Delete Configuration" will delete the whole configuration for this service and bring you back to the Service Overview.
Pressing "Cancel" will cancel the current change of the configuration for this service and bring you back to the Service Overview.
Pressing "Submit" will tell you, that the configuration has been updated and that the service will restart correspondingly.

Alternatively, you may also restart the service by clicking "Restart" in the upper right corner.
Selecting 'Services' on the left side menu will bring you back to the corresponding Services Overview.
All the services statuses on the overview page may be viewed by selecting "Refresh Statuses" in the upper right corner. The following screen will then display all the statuses for the different services in the overview:

To add a new Service, select "+ Add Service" in the upper right corner. A drop-down-menu will open, where you can choose, which service or app you want to add. Select the requested app and the following screen will display:

You can now select options and enter details, such as Service Name, Node /Arm, Associated Customer and Host.
Pressing "Cancel" will cancel the action and bring you back to the Services Overview.
Pressing "Submit" will tell you, that the configuration has been updated and that the service will restart correspondingly.
You will now also have the option to delete the whole new configuration, by pressing the new "Delete Configuration" button in the bottom right corner. It will then bring you back to the corresponding Services Overview.

Interfaces

To add, view or modify Interfaces, select 'Interfaces' on the left side menu. The following screen will open:

This will display any existing interfaces.
Note: The screen will display the first 25 rows, if there are more than 25 interfaces, these may be displayed by pressing the "Load All Results" button. Additionally, the view may be downloaded in Excel format by selecting "Download Results".
Interfaces may be filtered by Customer, Cluster and Node. They can also be filtered by the condition of field Name, Type, Customer, Cluster and Associated Nodes. In order to do so, just click on the corresponding arrow right next to the field name and select your choice.
Alternatively, you can also enter an interface name in the search field and search for it directly.
In order to see the corresponding Interfaces, click on the Interface name itself. The following screen will open:

Displayed are details and options for this interface, such as interface name, description, associated customer and so on.
Pressing "Submit" will let you know that your changes have been saved. See following screen:

You also have the possibility to see details for the corresponding Arm Bindings and Testing Endpoints for this very Interface. To see these details, just click on the corresponding tab (as seen above).
To go back to the Interfaces Overview, click on 'Interfaces' on the left side menu again.
To add a new Interface, click on "+ Add Interface* in the upper right corner. The following screen will open:

You can now enter the details for your new Interface, such as Type, Name, Description, Associated Customer and Associated Cluster.
Pressing "Cancel" will bring you back to the corresponding Interface Overview.
Pressing "Submit" will bring you to the following screen, where you can now see and enter more details for this new Interface:

Next, select the "Arm Bindings" tab to Bind interface to relevant node, enter IP address and credentials

Select Node from drop down, followed by Bind to Arm to bind the interface to relevant Core or remote arm. Next, select "Update / Set Credentials" and Submit

To verify that the interface is working correctly, select the "Test Connection" button

Customer(s)

Click on 'Customers' on the left side menu. The following screen will open:

Displayed are all existing Customers.
Note: The screen will display the first 25 rows, if there are more than 25 customers, these may be displayed by pressing the "Load All Results" button. Additionally, the view may be downloaded in Excel format by selecting "Download Results".
Customers mays be filtered by filter on field Name, Description, Nodes, Interfaces and Services. In order to do so, just click on the corresponding arrow right next to the field name and select your choice.
You can also enter a customer name in the search field and search for it directly.
In order to see the corresponding Customer, you can just click on the Customers name itself. The following screen will open:

You can now see the Customers name and the corresponding Microsoft TenantID and make changes, if you wish.
Pressing "Cancel" will bring you back to the Customers Overview.
Pressing "Delete Customer" will delete the whole customer and bring you back to the corresponding customers overview.
Pressing "Submit" will let you know, that your changes have been saved correspondingly, as on following screen:

Back in the overview, you can also create a new customer by clicking "+ Create New Customer" in the upper right corner. The following screen will open:

You can now enter the name and the corresponding Microsoft TenantID for your customer.
Pressing "Cancel" will cancel the action and bring you back to the customers overview.
Pressing "Submit" will let you know, that the new customer has been created and it will also add a "Delete Customer" button, where you can completely delete the newly created customer again (will take you back to the overview). See screen as follows:

If you go to "Customers" on the left side menu again now, you can see your newly created customer there correspondingly.

Clusters

Click on 'Clusters' on the left side menu. The following screen will open:

You can now see all the created Clusters.
Note: The screen will display the first 25 rows, if there are more than 25 Clusters, these may be displayed by pressing the "Load All Results" button. Additionally, the view may be downloaded in Excel format by selecting "Download Results".
Clusters can be filtered by field Name, Description, Subnet, and Interfaces. In order to do so, just click on the according arrow right next to the field name and select your choice.
You can also enter a cluster name in the search field and search for it directly.
In order to see the corresponding Cluster, you can just click on the Clusters name itself. The following screen will open:

You can now see and change certain details of the cluster, such as Name, Description and Subnet.
Pressing "Cancel" will bring you back to the Cluster Overview.
Pressing "Delete Cluster" will delete the whole cluster and bring you back to the corresponding clusters overview.
Pressing "Submit" will let you know that your changes have been saved as per following screen:

When in the Cluster Overview, you can also create a new Cluster, by clicking "+ Create New Cluster" in the upper right corner. The following screen will open:

You can now enter the requested name, description and subnet for your new cluster.
Pressing "Cancel" will bring you back to the Cluster Overview.
Pressing "Submit" will let you know that the new cluster has been created and will also now give you a button, where you can delete the newly created cluster again completely. See following screen:

To get back to the overview, press 'Clusters' on the left side menu.

Branding

The branding option allows for the application of company branding to the applications. Click on 'Branding' on the left side menu. The following screen will open:

You can now see details for Yarnapp Brandings, such as Name and Targets.
In order to see the corresponding Branding, you can just click on the Brandings name itself. The following screen will open:

You can now see the uploaded details for this branding and some more options.
Pressing "Delete Branding" will delete the whole branding package and bring you back to the corresponding overview.
Pressing "Back to Branding" will take you back to the branding overview.
Pressing "Migrate to this Package" will migrate to the selected branding package
To upload or install a new Branding, click on "+ Upload / Install Branding" in the upper right corner. This will open your explorer, where you can now pick the according file. Press 'open', the following screen occurs:

You can now see the uploaded details for this branding and some more options.
Pressing "Delete Branding" will delete the whole branding package and bring you back to the corresponding overview.
Pressing "Back to Branding" will take you back to the branding overview (which now shows your newly created branding) as per following screen:

Pressing "Migrate to this Package" will Migrate existing apps with an old package to the new selected branding package

Collecting Yarnman Logs

There may be instances where there is a requirement to collect logs to interrogate issues that may be encountered requiring further details. These logs are then downloaded in Tar format.
Click on 'Yarnman Logs' on the left side menu. The following screen will open:

You can now see a list of all the Yarnman Log Requests.
Note: The screen will display the first 25 rows, if there are more than 25 Logs, these may be displayed by pressing the "Load All Results" button. Additionally, the view may be downloaded in Excel format by selecting "Download Results".
In order to see the corresponding details of a log request, you can just click on 'view' in front of a log request and the following screen will open:

Displayed are the details concerning that very log request.
You also have the possibility to delete the corresponding tasks and logs, by pressing the "Delete Task & Logs" button in the upper right corner. This action will delete the selected logs and bring you back to the overview screen.
On top of the overview screen, you may also enter the corresponding node, the time frame and then request new logs accordingly. Once done, the following screen will open, you may now view all the details as per below screen shot:

In the upper right corner, under "Filename", you can also click on the corresponding Tar file, which then starts downloading.
To collect a new log, select the relevant node from drop down, select time period for log and select if task events should be added to log or not (generally this is not required)
Then select "Request Logs"

To download the new log (Tar) file, select the highlighted link

Authentication Databases

Yarnman users are authenticated against an authentication database where users and roles are managed. To access, select "Database" from left side menu which will bring up below screen

By default, there is a Central DB database for authentication where users and roles may be added. There is also the option to create new authentication databases as required
Selecting Database will bring up screen

Define Name, Description and optional association with Customer may be defined. From top right side of screen may be selected Users and Roles. Selecting the "Roles" option that is used to define roles for access brings up screen as below

where there are tabs for each of the existing Yarnlab applications configured. By default, there is a "default" role under each app where access can be defined using toggles. New role may be defined by selecting "+New Role" from top right hand of screen.
By selecting each of the tabs for corresponding app, the type of access for the relevant role may be defined using the toggles

To add/ manage users, select the "Users" tab from right hand main Database screenbe

New users may be added or existing users managed. To add a new user, select "+ New User"

Define username and password (if LDAP authentication is used, leave blank) populate details name, email, company as required, then select access Roles from dropdown, Submit

Authentication Access Policies

Authentication access policies defines items such as authentication method (local DB, LDAP or UDS) and the linked Database
Select "Access Policies" from menu. By default, there will be a Central DB-Only Policy that may be selected or modified or new policies may be defined as required

Selecting the policy will display screen

Here, you may populate/ change name, select authentication method from drop down menu, and the linked authentication database

Yarnman Management/ Utilities/ Specifications

Yarnman Server Specifications

Minimum recommended specifications for Yarnman running standard datasets. For larger datasets, this would need to be increased
2 x vCPU
4 GB vRAM
80 GB vStorage

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

Upgrade Yarnman - Apply a patch

Process to apply patch in Yarnman

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

Upgrade Yarnman – Linux Deps upgrade

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

1. Copy the update file:  yarnman-linux-bundle-master-<version>.tar.gz.sig to  /opt/yarnlab/install via SFTP
2. ssh into the server
3. Run command: cd /opt/yarnlab/yarnman
4. 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

1. 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

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

CD /opt/yarnlab/yarnman

1. 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        

1. Verify that app installed correctly in Yarnman Administration App Web GUI
2. 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                                                                                                                                                        

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

Database Update Process

To update DB in Yarnman using Fauxton

1. [http://<ip|] address of Yarnman>:5984/_utils

2. architect/yarnman
3. settings
4. change to 2.X.X (previous version than current)
5. node ./scripts/update-database.js

Note that firewall may need to be disabled to allow Fauxton access that will need to be replaced post update

Local Firewall Configuration

Configure on each host as required using ufw
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable
Additional rules are required on the core node for each arm deployed
sudo ufw allow from <ip address of arm> to any proto tcp port 5984,5986
sudo ufw allow from <ip address of arm> to any proto tcp port 6379,6380
Default Terminator Configuration (Testmate)
sudo ufw allow from any proto udp port 6700:6799

External Firewall Ports

ARM → Core
Couchdb tcp/5984 tcp/5986 tcp/6984
Redis tcp/6379 tcp/6380
SSH tcp/22
Core → Arm – Patch transfer
SSH tcp/22
User → Yarnman – Access to Yarnman
SSH tcp/22
HTTPS tcp/443
Customer → Arm - PWreset/Yarndoor/Prattler
HTTPS tcp/443
Prattler upload tcp/8444
Prattler WS tcp/8081
RTP udp/6700-6799 – required for Media
Arm → Customer UC Apps - Testmate
CTI/QBE. TCP 2748
LDAP tcp/389 tcp/636
RTP udp/6700-6799 (configurable)
WS AXL/RIS HTTP tcp/80 tcp/443 tcp/8443
SSH tcp/22
Core ↔ Core - HA only
Couchdb cluster tcp/9100-9200
Redis Cluster tcp/1000
Other Apps
Arm → CUCDM8
WS tcp/8181
Arm → VOSS4UC
WS tcp/443
Arm → Kurmi
WS tcp/443

Certificates

From Yarnman Menu - Select "Certificates"

To add a new Certificate - Select "Add New Certificate"

Name the Certificate, then "Select a certificate file to upload"

Then select the file to upload → then "Add"

To Add a new Certificate Authority, CA

From Yarnman Menu select "Certificates", then from Certificates page, select "Add New Certificate Authority"

Type the name of the CA → "Add" 

Certificates pre 2.5.6

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.
~/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 acheive 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.

Certificates - 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
Open Editor 'nano cert.cnf'
In the editor – complete following info
[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>
Sample

To generate CSR
sudo openssl req -config cert.cnf -new -subj "/C=<Country Name>/ST=<State Name>/L=<Locality Name>/O=<Organisation Name>/OU=<Organizational Unit>/CN=<Common Name>" -out CSR_File.csr -key ssl-key.pem  -passin pass:yarnman -sha512 -newkey rsa:4096
Sample
 

Backup and Restore

To 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 exist 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

SSH Password Recovery Process

The steps below describe the process of recovering and resetting the SSH password for a user.

This procedure assumes that password recovery is required for any user BUT root. 

1. Hold down the shift key during the boot of the VM to get into the GRUB console.

   

2. Select “Advanced options for Ubuntu”.

   

3. Select the latest kernel with recovery mode.

   

4. Select “root - Drop to root shell prompt”.

   

5. Normally here there would be a prompt for the root user password. If none is set (default) then just press ENTER key.

   

6. Remount the / partition with write rights using this command: # mount -rw -o remount /

   

7. Use the passwd command to change the password of any user.     Note: It may state that it is a Bad Password but it will accept any password

   

8. Exit the command prompt either by using Ctrl+d keys or exit.

9. Now reboot the machine either by resuming the recovery mode and using the reboot command there or by force.