The configuration flow and worksheets

You’ll build the airline’s first two LUNs on the practice DS8A50 the way careful teams do it: write the logical worksheet, have a script check it against the real hardware, generate the DS CLI commands in IBM’s order and run them as one script.

Practice shell note: the practice shell is our own teaching tool, not IBM software. Its capacity numbers come from simple formulas and the WWPNs of saat-host1 are made up, and real DS CLI output looks very close to this but isn’t identical. The success messages are IBM’s, while the two error messages in the break lab come from the practice shell. Data-at-rest encryption is on in the practice system, which is why ranks and pools take -keygrp 1.

1Start clean and make a profile for scripts

Scripts get a profile of their own so their output is always plain comma-separated rows. Save auto.profile in the lab folder next to ds8sim.py (it uses the security.dat from Lesson 2), or keep the one you made in Lesson 6 if you already have it.

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 lab.profile simctl reset
python ds8sim.py -cfg auto.profile lsarraysite -l

You should see this (after the notice lines and the reset message):

arsite,DA Pair,dkcap (10^9B),diskrpm,State,Array,diskclass,encrypt
S1,0,4800.0,65000,Unassigned,-,FlashCoreModule,supported
S2,0,4800.0,65000,Unassigned,-,FlashCoreModule,supported
S3,0,4800.0,65000,Unassigned,-,FlashCoreModule,supported
S4,0,4800.0,65000,Unassigned,-,FlashCoreModule,supported
S5,2,4800.0,65000,Unassigned,-,FlashCoreModule,supported
S6,2,4800.0,65000,Unassigned,-,FlashCoreModule,supported
S7,2,3840.0,65000,Unassigned,-,FlashTier2,supported
S8,2,3840.0,65000,Unassigned,-,FlashTier2,supported

This is what the checker reads for itself: which array sites exist and what drives they hold. There’s no file to export, because the script asks the DS8000 every time it runs and so never works from an old copy.

✅ Checkpoint: lsarraysite lists S1 to S8, and S1 and S2 hold FlashCoreModule drives.

2Fill in the logical worksheet

Save this as worksheet.csv. Each row is one decision: which array sites go into the pool pair, the RAID level, the encryption key group, which ports become FCP, the host and its two HBA WWPNs, and the volumes. Volume 2000 sits in LSS 20 (even) and 2100 in LSS 21 (odd), so each internal server owns one of them.

Save this as worksheet.csv:

section,key,value
pool,fb_sites,S1;S2
pool,raid,6
pool,keygrp,1
ports,fcp,I0031;I0040
host,name,saat-host1
host,type,Linux Server
host,wwpns,10000000C9A1B2C3;10000000C9A1B2C4
volumes,ids,2000;2100
volumes,cap_gib,100
volumes,sam,ese

✅ Checkpoint: worksheet.csv has 10 rows after the header.

3Write the checker and script builder

Save this as build_flow.py next to ds8sim.py. It runs there, on your laptop or a jump server and not on the DS8000, and the first thing it does is ask the DS8000 what exists (lsarraysite -l, lsioport, lskey).

It then checks the worksheet against those answers: licence keys applied, at least two arrays, real array sites, real FCP ports, ESE volumes when the sites hold FlashCore Modules, and 16-digit WWPNs. It only writes flow.txt, in IBM’s order, when every check passes.

Save this as build_flow.py:

# build_flow.py - check a DS8000 worksheet, then write a DS CLI script in IBM's configuration order
# Order from IBM Redbook SG24-8559-01, section 8.5 (FB only; CKD steps 8-9 left out)
# 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 sys
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))

def rows(name):
    with open(name, newline="") as f:
        return list(csv.DictReader(f))

ws = {(r["section"], r["key"]): r["value"] for r in rows(sys.argv[1] if len(sys.argv) > 1 else "worksheet.csv")}
lst = lambda s, k: [v for v in ws.get((s, k), "").split(";") if v]
site_class = {r["arsite"]: r["diskclass"] for r in dscli("lsarraysite", "-l")}   # live from the DS8000
port_ids = {r["ID"] for r in dscli("lsioport")}
key_names = {k["Activation Key"] for k in dscli("lskey", "IBM.2107-78SV001")}

problems = []
if "Base function" not in key_names:
    problems.append("licence: no Base function key; apply the keys first (Lesson 6)")
sites = lst("pool", "fb_sites")
if len(sites) < 2:
    problems.append("pool: use at least two arrays so each rank group gets one")
for s in sites:
    if s not in site_class:
        problems.append(f"pool: array site {s} does not exist on this system")
for p in lst("ports", "fcp"):
    if p not in port_ids:
        problems.append(f"ports: I/O port {p} does not exist on this system")
fcm = any(site_class.get(s) == "FlashCoreModule" for s in sites)
sam = ws.get(("volumes", "sam"), "standard")
if fcm and sam != "ese":
    problems.append("volumes: pools with FlashCore Modules take only thin (ESE) volumes; set sam to ese")
for w in lst("host", "wwpns"):
    if len(w) != 16:
        problems.append(f"host: WWPN {w} must be 16 hex digits")
if problems:
    print("WORKSHEET PROBLEMS:")
    print("\n".join("  " + p for p in problems))
    sys.exit(1)

kg, name = ws[("pool", "keygrp")], ws[("host", "name")]
out = ["# flow.txt - generated by build_flow.py",
       "# 1 licence keys must already be applied", "lskey IBM.2107-78SV001",
       "# 2-3 pool pair: one pool per rank group, then arrays and ranks"]
out += [f"mkextpool -rankgrp {g} -stgtype fb -keygrp {kg} fb_pool_{g}" for g in (0, 1)]
for i, s in enumerate(sites):
    out += [f"mkarray -raidtype {ws[('pool', 'raid')]} -arsite {s}",
            f"mkrank -array A{i} -stgtype fb -keygrp {kg} -extpool P{i % 2}"]
out += ["# 5 FC ports", "setioport -topology scsifcp " + " ".join(lst("ports", "fcp")),
        "# 6 host with its WWPNs",
        f"mkhost -type \"{ws[('host', 'type')]}\" -hostport {','.join(lst('host', 'wwpns'))} {name}",
        "# 7 volumes (even LSS in P0, odd LSS in P1) and mapping"]
ids = lst("volumes", "ids")
for v in ids:
    pool = "P0" if int(v[:2], 16) % 2 == 0 else "P1"
    out.append(f"mkfbvol -extpool {pool} -cap {ws[('volumes', 'cap_gib')]} -sam {sam} -name {name}_#h {v}")
out += [f"chhost -action map -volume {','.join(ids)} {name}", "lsextpool", "lsfbvol", "lshost"]
open("flow.txt", "w").write("\n".join(out) + "\n")
print(f"Worksheet OK: wrote flow.txt with {len([l for l in out if not l.startswith('#')])} commands")

At work you follow this pattern for every bigger change: check the plan against the live box from the jump server, generate the script, get a colleague to review it, and then run it.

✅ Checkpoint: build_flow.py is saved next to worksheet.csv and auto.profile.

4Generate the script

Run this:

python build_flow.py
Get-Content flow.txt

You should see this:

Worksheet OK: wrote flow.txt with 15 commands
# flow.txt - generated by build_flow.py
# 1 licence keys must already be applied
lskey IBM.2107-78SV001
# 2-3 pool pair: one pool per rank group, then arrays and ranks
mkextpool -rankgrp 0 -stgtype fb -keygrp 1 fb_pool_0
mkextpool -rankgrp 1 -stgtype fb -keygrp 1 fb_pool_1
mkarray -raidtype 6 -arsite S1
mkrank -array A0 -stgtype fb -keygrp 1 -extpool P0
mkarray -raidtype 6 -arsite S2
mkrank -array A1 -stgtype fb -keygrp 1 -extpool P1
# 5 FC ports
setioport -topology scsifcp I0031 I0040
# 6 host with its WWPNs
mkhost -type "Linux Server" -hostport 10000000C9A1B2C3,10000000C9A1B2C4 saat-host1
# 7 volumes (even LSS in P0, odd LSS in P1) and mapping
mkfbvol -extpool P0 -cap 100 -sam ese -name saat-host1_#h 2000
mkfbvol -extpool P1 -cap 100 -sam ese -name saat-host1_#h 2100
chhost -action map -volume 2000,2100 saat-host1
lsextpool
lsfbvol
lshost

Read the comments, which follow the Redbook’s numbered flow. Step 4 (thin volume monitoring) is a planning step and steps 8 and 9 are for CKD, so none of them show up here.

✅ Checkpoint: flow.txt starts with lskey and ends with lshost.

5Run the build

Run this:

python ds8sim.py -cfg lab.profile -script flow.txt

You should see this (after the notice and the lskey listing, which you know from Lesson 6):

CMUC00000I mkextpool: Extent pool P0 successfully created.
CMUC00000I mkextpool: Extent pool P1 successfully created.
CMUC00004I mkarray: Array A0 successfully created.
CMUC00007I mkrank: Rank R0 successfully created.
CMUC00004I mkarray: Array A1 successfully created.
CMUC00007I mkrank: Rank R1 successfully created.
CMUC00011I setioport: I/O Port I0031 successfully configured.
CMUC00011I setioport: I/O Port I0040 successfully configured.
CMUC00530I mkhost: The host saat-host1 is successfully created.
CMUC00025I mkfbvol: FB volume 2000 successfully created.
CMUC00025I mkfbvol: FB volume 2100 successfully created.
CMUC00531I chhost: The host saat-host1 is successfully modified.

And the three checks at the end:

Name      ID stgtype rankgrp status availstor (2^30B) %allocated available reserved numvols
===========================================================================================
fb_pool_0 P0 fb      0       below  99576             0          6372864   64       1
fb_pool_1 P1 fb      1       below  99576             0          6372864   64       1
Name            ID   accstate datastate configstate deviceMTM datatype extpool cap (2^30B) cap (10^9B) cap (blocks)
===================================================================================================================
saat-host1_2000 2000 Online   Normal    Normal      2107-900  FB 512   P0      100.0       -           209715200
saat-host1_2100 2100 Online   Normal    Normal      2107-900  FB 512   P1      100.0       -           209715200
Name       Type         State   Cluster
=======================================
saat-host1 Linux Server Offline -

There’s one pool per rank group with one volume in each, and both volumes are mapped to saat-host1. The host shows Offline because no HBA has logged in yet, which happens once the SAN is zoned (Lesson 14). Lessons 10 to 14 explain each of these commands step by step.

✅ Checkpoint: lsfbvol shows 2000 in P0 and 2100 in P1, and lshost lists saat-host1.