Licensed functions and activation keys

The practice shell already has a set of keys installed, the way a system looks after the SSR and a colleague have done the first steps. You’ll collect what IBM needs, read the keys and audit them against the real raw capacity.

Practice shell note: the practice shell is our own teaching tool, not IBM software. Its serial numbers, signature and licence values are made up for the lab, and it has no applykey command because keys only come from IBM for a real machine. Real DS CLI output looks very close to this but isn’t identical, and the wrong-ID message in the break lab is a practice shell message.

1Collect the data IBM ESS asks for

Run this:

python ds8sim.py -cfg lab.profile simctl reset
python ds8sim.py -cfg lab.profile lssi
python ds8sim.py -cfg lab.profile showsi IBM.2107-78SV001

You should see this (showsi shortened to the fields you need):

Name         ID               Storage Unit     Model WWNN             State  ESSNet
====================================================================================
ds8k-g10-lab IBM.2107-78SV001 IBM.2107-78SV000 A05   5005076303FFF0DD Online Enabled
Name             ds8k-g10-lab
ID               IBM.2107-78SV001
Storage Unit     IBM.2107-78SV000
Model            A05
Signature        5a7e-0d5a-8a50-0001
MTS              IBM.5341-78SV000

Note down three things for ESS: the machine type and serial from MTS (5341, serial 78SV000, ending in 0), the model A05, and the signature 5a7e-0d5a-8a50-0001. The ID ending in 1, IBM.2107-78SV001, is the storage image, and that’s the one applykey and lskey target.

✅ Checkpoint: You have the serial ending in 0, the model and the signature written down.

2Read the installed keys

Run this:

python ds8sim.py -cfg lab.profile lskey IBM.2107-78SV001

You should see this:

Activation Key                Authorization Level (TB) Scope
============================================================
Base function                 100.0                    All
Copy services                 100.0                    All
Encryption Authorization      on                       All
Global mirror (GM)            100.0                    All
zHPF                          on                       CKD
IBM HyperPAV                  on                       CKD
Thin Provisioning             on                       All
Easy Tier                     on                       All
z/OS Distributed Data Backup  on                       FB
Local Data-at-Rest Encryption on                       All
Metro mirror (MM)             100.0                    All
Metro/Global mirror (MGM)     100.0                    All
Operating environment (OEL)   100.0                    All
Parallel access volumes (PAV) on                       CKD
Point in time copy (PTC)      100.0                    All
RMZ Resync                    100.0                    CKD
Transparent Cloud Tiering     on                       All
z-synergy services            on                       CKD

The TB values are licensed capacities, and the on/off rows are functions that come with a bundle. Base function and OEL are 100 TB with scope All, and the CKD rows (zHPF, PAV, z-synergy) belong to the zsS bundle.

The Copy Services rows (MM, GM, MGM, PTC) are all at 100 TB.

✅ Checkpoint: You can point to the Base function row and its scope.

3Make a profile for scripts

Scripts need plain, comma-separated output. Rather than adding -fmt delim to every command, put it in a profile that only scripts use: save auto.profile in the lab folder next to ds8sim.py. It uses the security.dat from Lesson 2.

Save this as auto.profile:

hmc1: 10.0.0.1
username: admin
pwfile: security.dat
devid: IBM.2107-78SV001
banner: off
header: on
format: delim
delim: ,

Run this:

python ds8sim.py -cfg auto.profile lskey IBM.2107-78SV001

You should see this (first lines, after the notice):

Activation Key,Authorization Level (TB),Scope
Base function,100.0,All
Copy services,100.0,All

Banner off drops the Date/Time line, header on keeps the column names, and format delim with a comma gives one plain row per key. You don’t need to export anything to files, because the audit script asks the DS8000 directly.

✅ Checkpoint: The output starts with the Activation Key,Authorization Level (TB),Scope header.

4Write the licence audit

Save this as license_check.py next to ds8sim.py. It runs there, on your laptop or a jump server and not on the DS8000, and asks the DS8000 for the storage image ID (lssi), the array sites (lsarraysite -l) and the keys (lskey).

It then adds up the raw capacity of the array sites (8 drives each, decimal TB), compares that with the Base function level, and rounds any gap up to an orderable size using Table 7-2. That rounding rule is our reading of the table, and your IBM seller has the final word on quantities.

Save this as license_check.py:

# license_check.py - compare DS8000 licences (lskey) with raw capacity (lsarraysite)
# Rules from IBM Redbook SG24-8559-01, 7.1.3 and Table 7-2
# Runs on your workstation or jump server, not on the DS8000.
# It talks to the DS8000 only through the DS CLI (auto.profile: banner off, header on, format delim).
import csv, subprocess
DSCLI = ["python", "ds8sim.py", "-cfg", "auto.profile"]   # at work: ["dscli", "-cfg", "auto.profile"]

def dscli(*args):
    """Run one DS CLI command and return its rows as dictionaries."""
    out = subprocess.run(DSCLI + list(args), capture_output=True, text=True).stdout
    lines = [l for l in out.splitlines() if l and not l.startswith("SaatVedha") and not l.startswith("CMUC")]
    return list(csv.DictReader(lines))

TIERS = [(100, 10), (250, 15), (500, 25), (1250, 75), (3000, 175), (6000, 300), (12000, 600)]

def order_size(tb):
    """Smallest orderable licence size >= tb (our reading of Table 7-2)."""
    total = 0
    for high, step in TIERS:
        while total < tb and total < high:
            total += step
        if total >= tb:
            return total
    raise ValueError("more than 12,000 TB")

image = dscli("lssi")[0]["ID"]           # storage image ID (ends in 1), never typed by hand
sites = dscli("lsarraysite", "-l")
keys = {k["Activation Key"]: k for k in dscli("lskey", image)}

raw = sum(8 * float(s["dkcap (10^9B)"]) / 1000 for s in sites)   # 8 drives per array site
print(f"Storage image {image}")
print(f"Raw capacity: {raw:.2f} TB in {len(sites)} array sites")

bf = keys["Base function"]
level = float(bf["Authorization Level (TB)"])
print(f"Base function: {level} TB, scope {bf['Scope']}")
if level < raw:
    print(f"  GAP: Base function must cover all raw capacity. Order up to {order_size(raw)} TB.")
else:
    print("  OK: covers the raw capacity.")
if bf["Scope"] != "All":
    print("  NOTE: IBM suggests scope All for Base function and Copy services.")

cs = keys["Copy services"]
print(f"Copy services: {cs['Authorization Level (TB)']} TB, scope {cs['Scope']}"
      " (must cover all volumes in CS relationships; FlashCopy counts source + target)")

✅ Checkpoint: license_check.py is saved next to ds8sim.py and auto.profile.

5Run the audit

Run this:

python license_check.py

You should see this:

Storage image IBM.2107-78SV001
Raw capacity: 291.84 TB in 8 array sites
Base function: 100.0 TB, scope All
  GAP: Base function must cover all raw capacity. Order up to 300 TB.
Copy services: 100.0 TB, scope All (must cover all volumes in CS relationships; FlashCopy counts source + target)

This is a real finding. The lab system has 291.84 TB raw (six sites of 4.8 TB FlashCore Modules and two of 3.84 TB drives) but only 100 TB of Base Function, and since BF has to cover all raw capacity, the right order is 300 TB.

Copy Services at 100 TB is fine as long as no more than 100 TB of volumes take part in mirrors and FlashCopy, with FlashCopy sources and targets both counted.

On a real system you’d take this to your IBM seller before building more arrays. An increase is concurrent, and you apply the new key in the same way.

At work you can have a scheduler on the jump server (cron or Task Scheduler) run this audit every month and mail the report, so new arrays never get ahead of the licence.

✅ Checkpoint: The audit reports the Base function gap and suggests 300 TB.