From 5a6da37646091b112435b0110fbb4aca40f37c87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Sun, 23 Aug 2026 22:12:36 +0200 Subject: [PATCH 01/11] Release prep 4.0.0: SMP install package, pinned toolchain, ufsd 1.2.1 Makes `make package` produce an installable product instead of a bare load library, and clears two things that would have broken the release run itself. [distribution] follows ufsd and ftpd: the load modules go through SMP (FMID THTP400, target HTTPD.@VRM@.LINKLIB), the sample library rides beside it as its own XMIT restored by TSO RECEIVE. Both DD names fall out of the dataset names, so HTTPLOAD/AHTTPLOD is a one-shot choice -- it goes into the FMID's JCLIN and changing it later is a new functional level. THTP400 is verified free in the SMPPTS on mvsdev only; the CDS and ACDS store hashed member names, so LIST CDS/ACDS SYSMOD(THTP400) still has to answer RC 04 on both stands before the tag. All five modules ship, ABEND0C1 included: mbtdist packages every [[module]] and offers no exclude, and since 4.0.0 a module is inert unless a Parmlib route names it. samplib/httpd had DSN=HTTPD.LINKLIB hardcoded in its STEPLIB, so the shipped procedure would have pointed at an unversioned library while SMP installed into HTTPD.V4R0M0.LINKLIB. It now carries @LINKLIB@, the placeholder ufsd's and ftpd's procedures use, which mbtdist replaces while staging. docs/installation.md is new and wired in as the archive's README -- the generated install job tells the operator to read it, and without the file the package shipped a dangling instruction. It documents what differs from the other two products: APF failure is fatal here rather than a warning, UFSD is optional but takes static file serving with it, the shipped HTTPPRM0 routes to mvsMF, and removal needs UCLIN because the install accepts the FMID. VERSION said 4.0.0 while project.toml said 4.0.0-dev. mvsrelease.py searches each version file for the *current* string, so `make release VERSION=4.0.0` would have bumped project.toml, failed to find 4.0.0-dev in VERSION, and aborted before any commit -- leaving a modified tree and no tag. Both files now carry the full pre-release string, as ftpd's and ufsd's do. The toolchain pin moves to libc370 1.0.3 and the ufsd range to >=1.2.1, both released 2026-08-23. Verified: `make modules` builds all five clean under -Werror against the new ufsd, and `make package` produces the SYSMOD, both jobs and a samplib XMIT whose extracted procedure reads DSN=HTTPD.V4R0M0D.LINKLIB. --- VERSION | 2 +- docs/installation.md | 783 +++++++++++++++++++++++++++++++++++++++++++ mbt.lock | 4 +- project.toml | 90 ++++- samplib/httpd | 2 +- 5 files changed, 875 insertions(+), 6 deletions(-) create mode 100644 docs/installation.md diff --git a/VERSION b/VERSION index fcdb2e1..d9b058f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -4.0.0 +4.0.0-dev diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..5e7240f --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,783 @@ +# HTTPD Installation Guide + +This guide installs HTTPD on an MVS 3.8j system (TK4-, TK5, MVS/CE, or a custom +Hercules build) from the release distribution archive. + +The installation is managed by **SMP Release 4** — the SMP that ships with +MVS 3.8j, not SMP/E. That means the system keeps a record of what was +installed, and there is a supported way back out (see +[Removing HTTPD](#11-removing-httpd)). + +## Getting help + +**Report problems as a GitHub issue:** + + +That is the only place bug reports are tracked. Please include the two build +stamps HTTPD writes at startup (`HTTPD000I` and `HTTPD005I`, see +[step 9](#9-start-and-verify)) — they identify the exact build — plus the +console messages and, for an install problem, the job output. + +**Questions and general support** are on Discord: + + +--- + +Two placeholders are used throughout: + +| | | +|---|---| +| `` | the release, e.g. `4.0.0` — it appears in every shipped file name | +| `` | the same release as MVS dataset qualifier, e.g. `V4R0M0` | + +Both are already filled in inside the shipped jobs; you only need them to +recognise which file is which. + +--- + +## 1. What is in the archive + +| File | What it is | +|------|------------| +| `README.md` | this guide | +| `httpd--load.xmit` | the five load modules, as a TSO RECEIVE-ready XMIT | +| `httpd--samplib.xmit` | the sample library: STC procedure and configuration pattern | +| `httpd--alloc.jcl` | allocates the datasets SMP installs into — **run once** | +| `httpd--inst.jcl` | receives everything and installs it — repeatable | + +The load library holds five modules: + +| Module | What it is | +|--------|------------| +| `HTTPD` | the server itself — the only one a started task names | +| `HTTPDSRV` | display module: server control blocks (`/.dsrv`) | +| `HTTPDM` | display module: arbitrary storage (`/.dm`) | +| `HTTPDMTT` | display module: Master Trace Table, i.e. the console log (`/.dmtt`) | +| `ABEND0C1` | a deliberate-abend diagnostic used to exercise storage reclaim | + +**Only `HTTPD` runs unless you ask for the others.** Since 4.0.0 no module is +reachable unless a `MOD=` line in the configuration member names it, so the four +above are inert on a fresh install. That is deliberate: `/.dm` and `/.dmtt` hand +out arbitrary storage and the console log, and `ABEND0C1` abends on purpose. +See [step 7](#7-install-the-procedure-and-the-configuration). + +The sample library holds two members, `HTTPD` (the started task procedure) and +`HTTPPRM0` (the configuration pattern). + +Where everything ends up: + +``` +HTTPD..LINKLIB the load modules -- point STEPLIB here +HTTPD..SAMPLIB the patterns you copy from in step 7 +HTTPD..AHTTPLOD SMP's distribution library, the base a RESTORE returns to +``` + +--- + +## 2. Prerequisites + +- **MVS 3.8j** on Hercules, up and IPLed, with SMP 4 usable (the `SMPREC` and + `SMPAPP` procedures and the `SYS1.SMP*` datasets — present on TK4-/TK5 and + MVS/CE as shipped). +- **RAKF** — see [Authorisation](#authorisation) below. HTTPD does not start + without either RAKF or an APF list entry, and no configuration option turns + that off. +- **UFSD**, only if you want to serve static files — see below. +- **mvsMF**, only if you want the REST API the shipped configuration routes to + — see below. +- A userid authorised to submit jobs, to update a PROCLIB in the started-task + concatenation, and to update a PARMLIB. +- A way to upload a **binary** file to the host — see step 3. +- Roughly 15 cylinders of DASD: 10 for the two libraries the allocation job + creates, the rest for the two TSO RECEIVE targets. One of those, the staging + library, is scratched again by the last step of the install job. + +### UFSD is optional, and what it costs you is static files + +HTTPD serves static content from the **UFSD filesystem and nowhere else** — the +DD-based document root of 3.3.x is gone (4.0.0). `DOCROOT` names a UFS path, so +without the UFSD started task there is nothing to serve statically. + +Nothing about the *install* needs it: the SYSMOD declares no prerequisite, +`libufs` is linked statically into the load modules, and a UFS that does not +initialise is a warning, not a failure: + +``` +HTTPD044W UNABLE TO INITIALIZE FILE SYSTEM +``` + +The server starts, listens, and every `MOD=` route — mvsMF, the display modules +— works normally. Only static file requests fail. A CGI-only HTTPD is an +ordinary deployment. + +Note that `HTTPD001I` still reads `READY - SERVING /www` afterwards: it names +the **configured** document root, not a working filesystem. `HTTPD044W` is the +line that tells you the filesystem is not there, and it is written earlier in +the start. On a deployment that will never have UFSD, `UFS=0` in the +configuration member skips the initialisation altogether and the warning with +it. + +Install HTTPD now and add UFSD later if you want it: +, with its own guide at +[ufsd/docs/installation.md](https://github.com/mvslovers/ufsd/blob/main/docs/installation.md). + +Note that UFSD has to be **running**, not just installed — it is a started task +HTTPD talks to across address spaces. + +### mvsMF is what the shipped configuration expects + +`HTTPPRM0` ships with three active routes, all of them to **mvsMF** — the +z/OSMF-compatible REST API, which is a separate product: + +``` +MOD=MVSMF /zosmf/info AUTH=NONE +MOD=MVSMF /zosmf/services/authenticate AUTH=NONE +MOD=MVSMF /zosmf/* +``` + +If mvsMF is not installed, HTTPD starts and those routes register normally — the +program is not looked for until a request first matches. The failure then shows +up per request as + +``` +HTTPD908E EXTERNAL PROGRAM MVSMF could not be loaded (not found in STEPLIB?) +``` + +Comment the three lines out, or install mvsMF: +. Its load library has to be in the +STC's STEPLIB concatenation — HTTPD dispatches a module through the MVS LINK +SVC, which searches the task's own libraries. + +### RAKF is required for logins + +HTTPD has no user database of its own. Every login — the HTML form, HTTP Basic, +and the token endpoint — is verified by RAKF (RACINIT, SVC 244), and a `RES=` +route option is checked against a RAKF profile under the logged-in user's +identity. **On a system without RAKF nobody can log in.** + +A server whose routes are all `AUTH=NONE` never authenticates anybody and does +not need RAKF for that — but it still needs it for authorisation, below. + +The setup — the `HTTPD` user and its group — is step 8. + +### Authorisation + +HTTPD is link-edited `AC(1)` and needs to be APF-authorised: without it the LINK +SVC that dispatches every module and the RACF services behind every login are +both unavailable. + +It obtains authorisation itself at startup, which goes through **SVC 244 — and +that comes from RAKF**. The clean alternative is to add `HTTPD..LINKLIB` to +the APF list in `SYS1.PARMLIB(IEAAPF00)`. On MVS 3.8j the APF list is only read +at IPL, and the library name carries the version — so this is one IPL per +release, not one IPL ever. + +**With neither, HTTPD does not start.** Unlike FTPD, which warns and keeps +running, HTTPD treats this as fatal: + +``` +HTTPD012E HTTPD UNABLE TO DYNAMICALLY OBTAIN APF AUTHORIZATION +``` + +and `main()` returns the failing setup's return code without starting a +listener. Resolve this before step 5 — an install that completes cleanly will +still not start. + +The two routes are not equivalent in one respect that matters if you ever have +to debug HTTPD. An **APF entry** authorises the job step *before* program fetch, +so MVS loads HTTPD into subpool 252 **key 0** — authorised code must not be +patchable by problem-key code. **SVC 244** sets `JSCBAUTH` *after* the fetch and +cannot relabel storage that is already allocated, so the module stays key 8. +HTTPD runs problem state key 8 either way, which means that under an APF entry +it must never store into its own module storage. It does not, as of 4.0.0: the +server block is `main()`'s automatic storage, and the state that used to be +file-scope — the codepage pair, the saved STC ACEE, the Basic realm — lives +there with it (issue #197). + +You do not have to work out which route you got: HTTPD says so at startup, on +the line after the version banner. + +``` +HTTPD002I AUTHORIZED BY LIBRARY (MODULE KEY 0) APF list entry +HTTPD002I AUTHORIZED BY SVC (MODULE KEY 8) SVC 244, from RAKF +``` + +The key is inferred from the route rather than measured — an authorised job step +has its module fetched key 0, an unauthorised one key 8, and SVC 244 arrives too +late to change either. Neither line is a warning: both routes end in an +authorised started task, and which one you want is a site decision. Quote the +line in a bug report — it decides the storage key HTTPD's own module runs in. + +--- + +## 3. Upload the two XMIT files + +Both `.xmit` files are EBCDIC NETDATA streams. Upload them **in binary** — no +ASCII/EBCDIC translation, no CRLF conversion — into sequential datasets with +`RECFM=FB LRECL=80 BLKSIZE=3120`. + +**The dataset names are yours to choose.** The install job names them on its +own `RECEIVE` commands, so nothing depends on what you call them; you will +enter them once in step 6. This guide uses `IBMUSER.HTTPD.LOAD.XMIT` and +`IBMUSER.HTTPD.SAMP.XMIT`. + +Whether you have to allocate them first depends on the upload path: **FTPD** +and **IND$FILE** create the dataset from the attributes you supply, mvsMF and +most other FTP servers need it to exist. Where a method says *pre-allocate*, +allocate both as `DSORG=PS, RECFM=FB, LRECL=80, BLKSIZE=3120`, primary ~50 +tracks, secondary 20 (TSO or ISPF 3.2). + +Pick **one** method: + +### a) FTP — mvslovers/ftpd (no pre-allocation) + +FTPD creates the datasets from the attributes it is given (default port 2121): + +``` +ftp -P 2121 your-mvs-host +> binary +> put httpd--load.xmit 'IBMUSER.HTTPD.LOAD.XMIT' +> put httpd--samplib.xmit 'IBMUSER.HTTPD.SAMP.XMIT' +> quit +``` + +This is also the upload path to prefer when you are **upgrading**: the HTTPD you +are replacing is the one serving mvsMF, so uploading through mvsMF means +uploading through the thing you are about to stop. + +### b) mvsMF (z/OSMF-compatible REST API), via zowe + +Only when a *different* server is up, or you are not replacing this one. It +requires the datasets to **exist first**, so *pre-allocate*, then: + +``` +zowe zos-files upload file-to-data-set httpd--load.xmit \ + "IBMUSER.HTTPD.LOAD.XMIT" --binary +zowe zos-files upload file-to-data-set httpd--samplib.xmit \ + "IBMUSER.HTTPD.SAMP.XMIT" --binary +``` + +### c) Another FTP server (pre-allocate) + +*Pre-allocate* both datasets, then transfer **binary** into them — a plain +`binary` + `put`. Any `SITE` keywords for dataset attributes vary between +MVS 3.8j TCP/IP stacks (they are **not** the z/OS syntax); pre-allocating makes +them unnecessary. + +### d) IND$FILE (3270 emulator) + +No pre-allocation needed. Use your emulator's file transfer in **binary** mode +(no ASCII/CRLF translation) with `RECFM=FB LRECL=80 BLKSIZE=3120`. The exact +option syntax is client-dependent — consult its file-transfer documentation. + +--- + +## 4. Allocate the product datasets + +Submit `httpd--alloc.jcl` unchanged, unless you want a specific unit or +volume — the `UNIT=SYSDA` and the space on each DD are the only things worth +editing. + +It creates `HTTPD..LINKLIB` and `HTTPD..AHTTPLOD` and nothing else. +The libraries the next step receives into are deliberately **not** allocated +here: TSO RECEIVE creates its own target and refuses to merge into an existing +dataset. + +Expect `COND CODE 0000`. + +> **Run this once.** There is no DELETE step in it, on purpose. After the +> install, `HTTPD..AHTTPLOD` holds SMP's accepted copy of the modules; a +> re-run that scratched it would leave the SMP inventory reporting an install +> that is no longer on the system, and nothing would say so. To start over, +> reject the SYSMOD first — see [Removing HTTPD](#11-removing-httpd). + +--- + +## 5. Stop a running HTTPD + +Only relevant when you are upgrading. The APPLY writes into +`HTTPD..LINKLIB`, and each release has its own — so a running *older* HTTPD +does not block the install. It does, however, keep running the old modules until +you restart it (step 9) against the procedure you copy in step 7. + +``` +/P HTTPD +``` + +Two things worth knowing before you do: + +- **HTTPD refuses to start a second instance on a port already served** + (`HTTPD037E`), so a forgotten `/P` becomes a refused start rather than a + confusing half-working one. That check is keyed by port, so a deliberate + second server on another port still starts — which is a good way to try a new + build without touching the running one. +- If mvsMF is your upload or console channel, stopping HTTPD takes it with it. + Have another way in (FTPD, TSO, the Hercules console) before you stop the + server. + +--- + +## 6. Install + +Open `httpd--inst.jcl` and replace the two placeholder dataset names +with what you uploaded in step 3: + +``` + RECEIVE INDSN('CHANGE.ME.HTTPLOAD') - <- IBMUSER.HTTPD.LOAD.XMIT + RECEIVE INDSN('CHANGE.ME.SAMPLIB') - <- IBMUSER.HTTPD.SAMP.XMIT +``` + +Those are the only lines you have to change. Submit it. + +The job runs eight steps, each conditional on the one before, so it stops at +the first failure rather than building on it: + +| Step | What it does | +|------|--------------| +| `DELOLD` | scratches the RECEIVE targets, so the job can be re-run | +| `RECV1` | load XMIT → `HTTPD..HTTPLOAD` (a staging library) | +| `RECV2` | samplib XMIT → `HTTPD..SAMPLIB` | +| `RECV` | receives the SYSMOD into the SMP inventory | +| `APPLYCHK` | dry run — `APPLY` only proceeds if this ends RC 0 | +| `APPLY` | copies the five load modules into `HTTPD..LINKLIB` | +| `ACCEPT` | makes this level the base a later `RESTORE` returns to | +| `CLEANUP` | scratches the staging library, which is now spent | + +The SYSMOD travels inline in the job — there is no third file to upload. + +**What a good run looks like.** Every step `COND CODE 0000`, and in the SMP +output: + +``` +HMA3930 SYSMOD THTP400 SUCCESSFULLY RECEIVED +HMA2380 COPY SUCCESSFUL - MOD=HTTPD - LMOD=HTTPD - LIBRARY=LINKLIB + - RETURN CODE=00 +HMA2050 APPLY PROCESSING COMPLETED - HIGHEST RETURN CODE IS 00 +``` + +There is one `HMA2380` line **per module** — five of them. A run that copies +fewer has lost one, and the `APPLY` still ends RC 00, so count them. + +Then check `HTTPD..LINKLIB` really holds all five (ISPF 3.4). Do look: SMP +reports the library by **ddname**, and a ddname says nothing about which dataset +was behind it. + +SMP **copies** these modules rather than re-binding them, which is why the +`AC(1)` authorisation code on `HTTPD` and every module's custom entry point are +exactly what the build produced. + +--- + +## 7. Install the procedure and the configuration + +SMP does not touch your PROCLIB or PARMLIB, and that is deliberate: **the +product owns the patterns, your system owns the copies.** If SMP owned the +running procedure, every change you made to it would be silently replaced by +the next update. So this step is yours, and it is the one place where you have +to read what you are copying. + +Copy from `HTTPD..SAMPLIB`: + +| Member | Copy to | Adjust | +|--------|---------|--------| +| `HTTPD` | a PROCLIB in the started-task concatenation | usually not — `STEPLIB` already names this release's LINKLIB. Add mvsMF's library to it if you use mvsMF | +| `HTTPPRM0` | a PARMLIB | **yes — see below** | + +`SYS2.PROCLIB` is the usual home for the procedure. + +### Which PARMLIB + +The shipped procedure defaults to `D='SYS2.PARMLIB'`. **On TK5 that dataset +does not exist** — put the member in `SYS1.PARMLIB` and either edit `D=` in +your copy of the procedure, or override it when starting: + +``` +/S HTTPD,D='SYS1.PARMLIB' +``` + +On MVS/CE, `SYS2.PARMLIB` exists and the default is fine. `M=` selects the +member (default `HTTPPRM0`), so a second configuration can live alongside the +first. + +### The STC identity — `STCUSER` and `STCGRP` + +The shipped procedure logs the server on to `HTTPD/USER` at startup: + +``` +// STCUSER=HTTPD, +// STCGRP=USER +//HTTPD EXEC PGM=HTTPD,REGION=8M,TIME=1440, +// PARM='STCUSER=&STCUSER STCGROUP=&STCGRP' +``` + +RAKF has no started-procedures table: it decides only *that* a caller is an STC, +never *which* one, and hands every started task the same `STC/STCGROUP` account +— which on a stock profile set holds **ALTER on every dataset on the system**. +So HTTPD replaces it with a dedicated identity of its own (issue #177). Define +that userid in step 8. + +Two traps if you write your own procedure: + +- The START symbolic is `STCGRP` while the keyword the program parses is + `STCGROUP=` — a JCL symbolic parameter name is at most seven characters. +- `__start()` splits the PARM into `argv` on **blanks, not commas**. Joining the + two keywords with a comma hands the whole string to `STCUSER=`, and the group + is then silently wrong. + +If the logon fails the server **continues** on the inherited identity and says +so with `HTTPD004W`, so a profile typo is not an outage — but it is also not +what you asked for. Watch for that message where you expect `HTTPD004I`. + +### The DD statements — do not add SYSPRINT, SYSTERM or SYSIN + +HTTPD writes its own STDOUT/STDERR and reads STDIN through private DDs +(`HTTPDOUT`, `HTTPDERR`, `HTTPDIN`) so that a module cannot scribble into the +JES datasets an operator reads. The three conventional names are **refused**, +before `main()` runs: + +``` +HTTPD014E SYSPRINT DD NOT ALLOWED, HTTPD USES HTTPDOUT FOR STDOUT +HTTPD015E SYSTERM DD NOT ALLOWED, HTTPD USES HTTPDERR FOR STDERR +HTTPD016E SYSIN DD NOT ALLOWED, HTTPD USES HTTPDIN FOR STDIN +``` + +The shipped procedure already has the right set. Leave it alone unless you know +why you are changing it. + +### Editing HTTPPRM0 + +Every keyword in the shipped member is commented out, so a member copied +unchanged runs on the built-in defaults — **port 8080, document root `/www`** — +plus the three active `MOD=MVSMF` route lines. Four things are worth a look +before the first start: + +``` +PORT=8080 +DOCROOT=/www +REALM=MVS Development System +MOD=MVSMF /zosmf/* AUTH=TOKEN +``` + +- `PORT` is 8080 by default. Nothing on a stock MVS 3.8j contends for it. +- `DOCROOT` is a **UFS path**, and it must exist in a mounted UFSD filesystem. + Without UFSD, leave it and expect `HTTPD044W` (step 2). +- `REALM` defaults to the system's SMF ID — unambiguous, but meaningless to a + user. It is what a browser shows in its Basic credential dialog. +- The `MOD=MVSMF` lines are the ones to review first. Comment them out if you + have no mvsMF. + +**Read the auth model before you publish anything.** Authentication is declared +per route and nowhere else — there is no server-wide login keyword, and the +`LOGIN` keyword of earlier versions is retired: + +``` +MOD=MVSMF /zosmf/* AUTH=TOKEN program route, gated +LOC=/admin/* AUTH=BASIC static prefix, gated +LOC=/* AUTH=NONE static prefix, public on purpose +``` + +- **A route without `AUTH=` is public**, and so is any path no route claims at + all. There is no global default left to fall back on. +- The modes are `NONE`, `FORM` (HTML login form), `BASIC` (401 + + `WWW-Authenticate`) and `TOKEN` (a bare 401 for API clients that handle it + themselves). A value that is none of these refuses the route and the server + **does not start** — `HTTPD411E` then `HTTPD420E`. That is on purpose: a + policy silently weakened is worse than a server that will not start. +- `AUTH=` does not select which credentials are accepted. Every route accepts + all of them, because they are resolved before the route is matched. It selects + *whether* a login is needed and *how* a missing one is challenged. +- A member still carrying `LOGIN=ALL` / `CGI` / `GET` / `HEAD` / `POST` is a + **fatal** configuration error (`HTTPD048E`), because ignoring it would publish + every route without an `AUTH=` of its own. `LOGIN=NONE` was the default and is + merely warned about (`HTTPD048W`). Convert to `AUTH=` per route, then delete + the line. + +The display modules deserve their own warning. `MOD=HTTPDM /.dm` with no `AUTH=` +hands anyone who can reach the port arbitrary storage reads, and `/.dmtt` hands +them the console log. If you enable them, gate them: + +``` +MOD=HTTPDSRV /.dsrv AUTH=FORM +MOD=HTTPDM /.dm AUTH=BASIC +MOD=HTTPDMTT /.dmtt AUTH=BASIC +``` + +A `#` or `*` in the first column comments a line out. The full keyword reference +is [configuration.md](https://github.com/mvslovers/httpd/blob/main/docs/configuration.md). + +--- + +## 8. Set up RAKF + +Without this, HTTPD cannot authorise itself and does not start (step 2), and no +client can log in. + +1. Add the `HTTPD` user to `SYS1.SECURE.CNTL(USERS)`, default group `USER`: + + ``` + HTTPD USER DEFAULT-GROUP(USER) + ``` + + This is the identity from `STCUSER`/`STCGRP` in step 7. It needs **READ** on + whatever HTTPD itself opens before a client identity exists: the PARMLIB + member, the document root, the log DDs. + + It does **not** need `FACILITY SVC244`. HTTPD acquires APF authorisation at + start and releases it at `/P HTTPD`, and it restores the STC account it + started under immediately before the release — so both SVC 244 calls are made + by the same account, rather than requiring the profile on every system. + +2. Optionally define profiles for any route that carries `RES=class:resource`. + A `RES=` naming a resource **no profile covers** is not an error and does not + deny: SAF calls an unprotected resource allowed, so the authorisation stage + does nothing and only the `AUTH=` stage is left. HTTPD says so at startup: + + ``` + HTTPD425W NO PROFILE FOR FACILITY:HTTPD.ADMIN -- /admin/* NOT GATED + ``` + +3. Reload: `/F RAKF,RELOAD` + +--- + +## 9. Start and verify + +``` +/S HTTPD default member (HTTPPRM0) +/S HTTPD,M=HTTPPRM1 alternate config member +/S HTTPD,D='SYS1.PARMLIB' alternate PARMLIB -- TK5, see step 7 +``` + +A healthy start ends in `HTTPD001I … READY`: + +``` +HTTPD000I HTTPD (A69A370) STARTING +HTTPD005I LIBC370 1.0.3 (58767B3) +HTTPD002I AUTHORIZED BY SVC (MODULE KEY 8) +HTTPD004I STC IDENTITY SET TO HTTPD/USER VIA RACINIT +HTTPD036I MODULE MVSMF REGISTERED FOR /zosmf/info +HTTPD036I MODULE MVSMF REGISTERED FOR /zosmf/* +HTTPD054I LISTENING ON ANY PORT 8080 +HTTPD061I STARTING SOCKET THREAD TCB(9CD9D0) TASK(10CFC8) STACKSIZE(32768) +HTTPD061I STARTING WORKER(11ED48) TCB(9CD420) TASK(120FC8) STACKSIZE(65536) +HTTPD001I HTTPD READY - SERVING /www +``` + +That transcript is a system with UFSD running. Without it, `HTTPD044W` appears +between `HTTPD004I` and `HTTPD054I` — and the last line still reads +`SERVING /www`, because it names the configured document root rather than a +working filesystem (step 2). + +The two build stamps identify exactly what is running: `HTTPD000I` gives the +version and the commit it was built from, `HTTPD005I` the libc370 it was linked +against — quote both in a bug report. A build made from a modified working tree +marks its hash `-DIRTY` and adds `HTTPD006W`; a released build never does. + +**The configuration is not echoed at startup** — not the member, not the +codepage, not the task limits. `/F HTTPD,D CONFIG` reports all of it on demand, +and that one look after the first start is worth taking: it prints what HTTPD +*parsed*, not what the member says, so a typo that fell back to a default is +visible there and nowhere else. + +**A refused start is recognised by the step return code, never by a console +string.** A start refused by initialisation ends `CC 0008`; a clean `/P HTTPD` +ends `CC 0000`. The first console line is the cause (`HTTPD037E`, `HTTPD028E`, +`HTTPD030E`, `HTTPD031E`, `HTTPD420E`, `HTTPD033E` or `HTTPD090E`); everything +under it is the ordinary stop sequence and says nothing about what went wrong. +The full contract is in +[messages.md](https://github.com/mvslovers/httpd/blob/main/docs/messages.md). + +Then reach it from a client: + +``` +curl -v http://your-mvs-host:8080/zosmf/info mvsMF installed +curl -v http://your-mvs-host:8080/ static, needs UFSD +``` + +Operator commands: + +``` +/F HTTPD,DISPLAY Config the configuration actually in effect (D C) +/F HTTPD,DISPLAY Stats request/error/byte counters, SMF level (D S) +/F HTTPD,DISPLAY Threads the worker pool, block by block (D T) +/F HTTPD,DISPLAY Ports the listening port (D P) +/F HTTPD,DISPLAY Login who is logged in (D L) +/F HTTPD,DISPLAY Version build stamps again (D V) +/F HTTPD,DISPLAY TIme server time and offset (D TI) +/F HTTPD,DISPLAY Memory xxxxxx[,nnn] (D M) +/F HTTPD,SET MIntask n resize the worker pool +/F HTTPD,SET MAxtask n +/F HTTPD,SET Stats NONE|ERROR|AUTH|ALL [RESET] +/F HTTPD,HELP every MODIFY command +/P HTTPD orderly stop (HTTPD099I SHUTDOWN COMPLETE) +``` + +Commands abbreviate to the capitalised prefix, which is why `DISPLAY Threads` +and `DISPLAY TIme` need one and two letters respectively. + +--- + +## 10. What HTTPD serves + +Two kinds of route, both declared in the configuration member, both carrying the +same per-route auth policy: + +- **`MOD=` — a program.** An MVS load module dispatched on the worker thread's + own TCB through the LINK SVC, once per request. mvsMF is the one that matters + in practice; the three display modules ship with the server. +- **`LOC=` — a static prefix.** No program: the request falls through to the + static file handler on `DOCROOT`, but the prefix still carries `AUTH=`/`RES=`. + This is how a static subtree gets a login without a CGI. + +Routes are tested **in order** and matched exactly unless they carry a `*`, so +list specific prefixes before a catch-all — a `LOC=/*` placed above +`MOD=MVSMF /zosmf/*` shadows it. + +HTTP/1.1 with persistent connections and chunked transfer encoding is the +default for 1.1 clients; 1.0 clients always get `Connection: close`. + +The full reference is +[configuration.md](https://github.com/mvslovers/httpd/blob/main/docs/configuration.md); +writing your own module is +[development.md](https://github.com/mvslovers/httpd/blob/main/docs/development.md). + +--- + +## 11. Removing HTTPD + +Because the installation is SMP-managed, there is a defined way back — but it is +**not** the `RESTORE` followed by `REJECT` that SMP documentation leads you to +expect. The install job accepts the FMID in the same run as the APPLY, and an +accepted function SYSMOD refuses both: `RESTORE` because it was accepted, +`REJECT` because accepting removed from `SYS1.SMPPTS` the control statements it +works from. The route that does work is a `UCLIN` job. + +What this release put on the system: + +| | | +|---|---| +| FMID | `THTP400` | +| Load modules | `HTTPD`, `HTTPDSRV`, `HTTPDM`, `HTTPDMTT`, `ABEND0C1` | +| Target library | `HTTPD..LINKLIB` | +| Distribution library | `HTTPD..AHTTPLOD` | +| Sample library | `HTTPD..SAMPLIB` | + +**1. Stop the server:** `/P HTTPD` + +**2. Cut the FMID out of the SMP inventory.** Submit this — it edits the CDS and +the ACDS and touches no library: + +``` +//HTTPDUCL JOB (SYS),'HTTPD UNINSTALL', +// CLASS=A,MSGCLASS=H,MSGLEVEL=(1,1), +// REGION=4096K +//UCLIN EXEC SMPAPP +//SMPCNTL DD * + UCLIN CDS . + DEL SYSMOD(THTP400) MOD(HTTPD) . + DEL SYSMOD(THTP400) MOD(HTTPDSRV) . + DEL SYSMOD(THTP400) MOD(HTTPDM) . + DEL SYSMOD(THTP400) MOD(HTTPDMTT) . + DEL SYSMOD(THTP400) MOD(ABEND0C1) . + DEL MOD(HTTPD) . + DEL MOD(HTTPDSRV) . + DEL MOD(HTTPDM) . + DEL MOD(HTTPDMTT) . + DEL MOD(ABEND0C1) . + DEL LMOD(HTTPD) . + DEL LMOD(HTTPDSRV) . + DEL LMOD(HTTPDM) . + DEL LMOD(HTTPDMTT) . + DEL LMOD(ABEND0C1) . + DEL SYSMOD(THTP400) . + ENDUCL . + UCLIN ACDS . + DEL SYSMOD(THTP400) MOD(HTTPD) . + DEL SYSMOD(THTP400) MOD(HTTPDSRV) . + DEL SYSMOD(THTP400) MOD(HTTPDM) . + DEL SYSMOD(THTP400) MOD(HTTPDMTT) . + DEL SYSMOD(THTP400) MOD(ABEND0C1) . + DEL MOD(HTTPD) . + DEL MOD(HTTPDSRV) . + DEL MOD(HTTPDM) . + DEL MOD(HTTPDMTT) . + DEL MOD(ABEND0C1) . + DEL SYSMOD(THTP400) . + ENDUCL . +/* +//LIST EXEC SMPAPP +//SMPCNTL DD * + RESETRC . + LIST CDS SYSMOD(THTP400) . + LIST ACDS SYSMOD(THTP400) . +/* +// +``` + +Every `DEL` reports `HMA2550 UPDATE COMPLETE`, and each `UCLIN` block ends +`RC 00`. + +**3. Read the LIST — this is the actual result.** Both zones must answer: + +``` +THE FOLLOWING SELECTED ENTRIES WERE NOT FOUND OR WERE NOT ELIGIBLE +FOR PROCESSING + TYPE NAME + SYSMOD THTP400 +``` + +with `HIGHEST RETURN CODE IS 04`. **RC 04 and an empty list means the FMID is +free.** Both zones matter: the CDS records what is applied, the ACDS what is +accepted, and they are separate inventories — an id gone from one and present in +the other is not free. + +**4. Scratch the libraries.** `UCLIN` edits the inventory only; both datasets are +still there, and a re-install's allocation job would fail on them: + +``` + DELETE HTTPD..LINKLIB NONVSAM SCRATCH PURGE + DELETE HTTPD..AHTTPLOD NONVSAM SCRATCH PURGE +``` + +Leave `HTTPD..SAMPLIB` alone if you like — the install job's `DELOLD` step +scratches it on its own. + +**5. What is not removed, because SMP never owned it:** the procedure and the +configuration member you copied in step 7, and your RAKF definitions. Those are +yours to delete. + +> The `RESTORE`/`REJECT` behaviour above was measured on 2026-08-14 against an +> accepted FMID from a package built by this same generator, on an MVS/CE system +> running SMP 4 level 04.48. It is a property of SMP 4 and of accepting a +> function SYSMOD, not of any one product — but the `UCLIN` job above has not +> itself been run against `THTP400`. Read the `LIST` output rather than trusting +> the `DEL` cards. + +--- + +## Troubleshooting + +| Symptom | Likely cause | +|---------|--------------| +| Allocation job fails, dataset already exists | It was already run. Do not force it — see the warning in step 4 | +| `RECV1`/`RECV2` fails, target exists | Something else allocated it. RECEIVE refuses to merge; scratch it and re-run | +| `APPLYCHK` ends non-zero, `APPLY` skipped | Read the SMP output — the check exists to stop before anything is written. A missing DD is the usual cause | +| `APPLY` RC 00 but fewer than five `HMA2380` lines | A module was lost. Count them, then look in the library itself | +| SMP reports success, but a module is not where you expected | A ddname says nothing about the dataset behind it. Check the JCL, then look at the library itself | +| `S806` (module not found) at `/S HTTPD` | `STEPLIB` in the procedure does not name the LINKLIB the APPLY wrote to | +| `/S HTTPD` rejected — procedure not found | Procedure not copied into a PROCLIB in the started-task concatenation | +| `HTTPD012E … UNABLE TO DYNAMICALLY OBTAIN APF AUTHORIZATION`, no listener | No RAKF (so no SVC 244) and no APF entry — step 2. This one is fatal, not a warning | +| `HTTPD014E`/`015E`/`016E` and the step ends before any banner | A `SYSPRINT`, `SYSTERM` or `SYSIN` DD in the procedure — step 7 | +| `HTTPD037E HTTPD IS ALREADY ACTIVE ON PORT n` | An older instance still holds the port. `/P HTTPD` first — step 5 | +| `HTTPD004W RACINIT ENVIR=CREATE FAILED` | The `STCUSER`/`STCGRP` userid is not defined to RAKF — step 8. Not fatal; the server runs on the inherited STC identity | +| `HTTPD044W UNABLE TO INITIALIZE FILE SYSTEM` | UFSD is not running. Module routes are unaffected; only static files fail — step 2. `HTTPD001I` still names the configured `DOCROOT`, so it is not the line to read here | +| `HTTPD908E EXTERNAL PROGRAM MVSMF …` on every `/zosmf/` request | mvsMF is not in the STC's STEPLIB — step 2. The parenthetical "(not found in STEPLIB?)" is a guess; the real abend code is in the `IEA703I` line beside it, and `106-0F` means storage, not a missing member | +| `HTTPD420E ROUTE AUTHORIZATION POLICY INCOMPLETE`, `CC 0008` | A route's `AUTH=` value is not `NONE`/`FORM`/`BASIC`/`TOKEN`, or a `LOGIN=` line survives in the member — step 7 | +| `HTTPD425W NO PROFILE FOR …` | A `RES=` names a resource no RAKF profile covers, so that route is gated by `AUTH=` alone — step 8 | +| A route answers `200` to anyone | It carries no `AUTH=`, or no route claims the path at all. Both are public by design — step 7. `/.dsrv?target=MOD` prints the policy each route actually got | +| `401` on a route showing `AUTH=NONE` | Not HTTPD's gate. mvsMF runs its own auth track on `/zosmf/*` — establish which layer answered before debugging HTTPD's | +| `S106` at start on a freshly installed library | The XMIT was uploaded in text mode. Re-upload in **binary** and re-run the install job | +| The step ends `CC 0000` but nothing was ever served | A clean `/P HTTPD` and a refused start are `CC 0000` and `CC 0008`. If it is 0000, the server ran — look for what stopped it | + +For the complete message reference, see +[messages.md](https://github.com/mvslovers/httpd/blob/main/docs/messages.md). diff --git a/mbt.lock b/mbt.lock index becc950..9f6ea16 100644 --- a/mbt.lock +++ b/mbt.lock @@ -1,6 +1,6 @@ { "mvslovers/ufsd": { - "sha256": "a64fb1510760565890c714074cd7bcb5bdb2283c3e78c4b771cc7070d3cc0078", - "version": "1.2.0" + "sha256": "3efc6ed09d63cb06afd8b6adf4e411d85efd48511cca266f0ada7b5560ebd5b0", + "version": "1.2.1" } } diff --git a/project.toml b/project.toml index 3f272a9..ad75ee0 100644 --- a/project.toml +++ b/project.toml @@ -13,7 +13,7 @@ type = "application" # first 1.0.0 attempt shipped reporting an unreleased runtime nobody could # reproduce from a tag. HTTPD005I names the runtime it linked against, so an # unpinned release build makes that line unreproducible in exactly the same way. -libc370 = "1.0.2" +libc370 = "1.0.3" [build] # The build stamp behind HTTPD000I/001I/006W is not injected here: mbt @@ -49,7 +49,7 @@ cflags = [ cflags = ["-Wno-error"] [dependencies] -"mvslovers/ufsd" = ">=1.2.0" +"mvslovers/ufsd" = ">=1.2.1" # -- Internal autocall archive ------------------------------------ # All of httpd's objects, archived into build/httpdint.a. Every module @@ -282,5 +282,91 @@ headers = [ "include/types.h", ] +# -- Distribution (SMP4 install package) -------------------------- +# Turns `make package` into an installable product, the same two transports +# ufsd and ftpd ship with: +# +# load modules -> XMIT -> staging HTTPLOAD -> SMP ++MOD -> HTTPD..LINKLIB +# samplib/ -> XMIT -> TSO RECEIVE -> HTTPD..SAMPLIB +# +# SMP *copies* the host-bound modules rather than re-binding them (a COPY-style +# ++JCLIN is what says so), which is what keeps HTTPD's ac = 1 and every custom +# entry point exactly as ld370 set them. The sample library stays outside SMP: +# an MCS card ends at column 72 and HTTPPRM0 has comment lines reaching column +# 80, so routing the configuration pattern through the SYSMOD would make it +# answer to a delivery mechanism. The datasets are versioned, so every release +# brings a fresh SAMPLIB anyway -- there is no in-place update for SMP to +# manage. +# +# samplib/httpd carries @LINKLIB@ in its STEPLIB, which mbtdist replaces with +# the versioned target while staging -- the same placeholder ufsd's and ftpd's +# procs use, and the reason the shipped proc points at the library SMP actually +# installed into rather than at a name fixed when the file was written. Do not +# mention a placeholder in a nearby comment: the substitution runs over the +# whole member, and a 21-character dataset name landing in a comment line is how +# a proc that fit an FB-80 card stops fitting one. +# +# Every value is a dataset name; the ddname SMP addresses it by is always the +# last qualifier, so LINKLIB, SAMPLIB, HTTPLOAD and AHTTPLOD fall out of the +# names. @VRM@ becomes V4R0M0 at package time (V4R0M0D while the version still +# carries -dev). ufsd/ftpd spell these LOAD / ALOD, which for +# a five-letter product would be nine characters; HTTPLOAD/AHTTPLOD keeps the +# suffix and drops the letter, rather than keeping HTTPD and truncating the +# suffix (HTTPDLOD/AHTTPDLD). Both names go into the FMID's JCLIN, so this is a +# one-shot choice -- changing it later is a new functional level. +# +# All five [[module]] entries ship, ABEND0C1 included: mbtdist packages every +# module and offers no exclude. Deliberate rather than overlooked -- since +# 4.0.0 a module is inert unless a Parmlib route names it, and the shipped +# HTTPPRM0 leaves its /.abend line commented out. It is the acceptance vehicle +# for the storage reclaim (#154/#174), and a diagnostic that is present but +# unreachable is worth more than one an operator would have to rebuild to use. +[distribution] +# Shipped into the archive as README.md, which is the name the generated install +# job points at ("See the README for which member goes where"). Without it the +# package tells the operator to read a file it does not contain. +readme = "docs/installation.md" + +[distribution.smp] +# One FMID per minor release, spent exactly once: it names a functional level, +# and a changed one is a new level. Patches on top of it ship as PTFs. 4.0.x +# is THTP400; a later 4.1.0 becomes THTP410 and is installed as a clean cut +# (RESTORE + REJECT the old, then receive the new). The T stays clear of the +# E??nnnn namespace MVS 3.8j's own function SYSMODs occupy (EBB1102 is 3.8j +# itself, alongside EAS1102, EBT1102, EDE1102, ...). +# +# NOT yet verified the way TFTP100 and TUFS120 were, and the difference matters. +# What is measured is the SMPPTS on mvsdev -- 1544 SYSMODs scanned, no THTP400 +# (smp-todo.md §2) -- and the PTS shows only what was *received*. The CDS and +# ACDS store hashed member names, so LIST CDS SYSMOD(THTP400) and LIST ACDS +# SYSMOD(THTP400) are the only way to see what is actually applied or accepted. +# Both stands (mvsdev, drnmig3a) still have to answer RC 04 with an empty list +# before the 4.0.0 tag. A test install must use a throwaway id -- a +# half-applied FMID leaves this one occupied, and smp-todo.md reserves TTST400 +# for exactly that. +fmid = "THTP400" +system = "Z038" + +# Empty despite the [dependencies] entry on ufsd, which is a *build* time one: +# libufs is linked statically, so nothing of ufsd has to be installed for the +# load modules to run. At run time it is soft even though 4.0.0 serves static +# files from UFS and nowhere else: ufs_sys_init() failing is HTTPD044W and the +# server keeps running, so every MOD= route -- mvsMF, the display modules -- +# works on a system with no UFSD at all. REQ(TUFS120) would therefore refuse +# the install wherever UFSD is absent, for a facility that already degrades on +# its own. The installation guide documents UFSD as an optional runtime +# prerequisite instead, which is also how ufsd itself treats RAKF. +prereq = [] + +accept_fmid = true # accept the FMID once so a PTF can be RESTOREd +lklib = "HTTPD.@VRM@.HTTPLOAD" # staging: what the load XMIT is received into +target = "HTTPD.@VRM@.LINKLIB" # where the load modules end up +distlib = "HTTPD.@VRM@.AHTTPLOD" + +[[distribution.library]] +dir = "samplib" +target = "HTTPD.@VRM@.SAMPLIB" + +# -- Release ------------------------------------------------------ [release] version_files = ["VERSION"] diff --git a/samplib/httpd b/samplib/httpd index 9af317c..a61d55e 100644 --- a/samplib/httpd +++ b/samplib/httpd @@ -36,7 +36,7 @@ //* PARM is space-separated: __start() splits argv on blanks, not commas. //HTTPD EXEC PGM=HTTPD,REGION=8M,TIME=1440, // PARM='STCUSER=&STCUSER STCGROUP=&STCGRP' -//STEPLIB DD DISP=SHR,DSN=HTTPD.LINKLIB +//STEPLIB DD DISP=SHR,DSN=@LINKLIB@ //SYSUDUMP DD SYSOUT=* //HTTPDERR DD SYSOUT=* //HTTPDOUT DD SYSOUT=* From ff819cdf86767efc85047f5fbafe5e693ceb2646 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Sun, 23 Aug 2026 22:12:56 +0200 Subject: [PATCH 02/11] Reconcile smp-todo.md with the generated distribution The document planned by hand what mbt now generates, and it read as current while being wrong in several places. Its first two links -- ../SMP-COOKBOOK.md and ../SMP-INSTALLATION.md -- point at files that no longer exist. It listed six load modules including HTTPJES2 and HTTPDSL, which 4.0.0 stopped building. And its question round proposed two answers the [distribution] block settles the other way. Dropped: the spike (done 2026-08-08 in ../smptest, which proved SMP copies the LKLIB module rather than re-binding it), the MCS/JCLIN/allocation generators, and the plan to ship the sample library as ++MAC elements inside the SYSMOD -- an MCS card ends at column 72 and HTTPPRM0 has comment lines reaching 80. Recorded as reversed rather than quietly changed: - The target is HTTPD.@VRM@.LINKLIB, not SYS2.LINKLIB. Versioned product datasets mean no IPL for an APF entry and no collision with a system library, and the procedure keeps its STEPLIB. That answers the old trap T6: the SVC 244 self-authorization path stays the normal case. - ACCEPT rides along, where the old F4 said "never". Accepting the FMID fills the distribution library, which is the base a later RESTORE of a PTF returns to; without it a RESTORE would delete the module instead of reverting it. The cost is that the FMID becomes permanent and removal needs UCLIN. Service is still never accepted. What is left is what is actually open: the LIST CDS/ACDS check for THTP400 on both stands, a test install on the throwaway TTST400, the UFS webroot SMP cannot deliver, and whether to ship a setup job at all. The traps that still bite are kept; T8 and T5 are struck with the reason they no longer apply. --- smp-todo.md | 581 +++++++++++++++++++--------------------------------- 1 file changed, 213 insertions(+), 368 deletions(-) diff --git a/smp-todo.md b/smp-todo.md index ce78e5a..638d485 100644 --- a/smp-todo.md +++ b/smp-todo.md @@ -1,277 +1,110 @@ -# SMP-Installation httpd — offene Punkte und TODOs - -> **Erprobtes Rezept — hier zuerst nachsehen:** [`../SMP-COOKBOOK.md`](../SMP-COOKBOOK.md) -> **Konzept, Belege und Handbuchzitate:** [`../SMP-INSTALLATION.md`](../SMP-INSTALLATION.md) -> -> Dieses Dokument beantwortet nicht *wie* SMP funktioniert — das steht dort. -> Hier steht, **was für httpd noch fehlt** und in welcher Reihenfolge es -> abgearbeitet wird. - -Ziel: eine **Testinstallation von httpd über SMP4** auf `mvsdev` — gebaut aus dem -aktuellen `4.0.0-dev`-Stand, inklusive SAMPLIB und UFS-Disk für das WWW-Root. -Sie ist die Generalprobe für das spätere Release der finalen `4.0.0`. - -Ablauf: **§1 Fragerunde → §3 Spike → §4–§6 Ausbau → §8 Abnahme.** -Die Fragen in §1 sind vor dem ersten Schreibzugriff zu klären; §2 listet, was -bereits verifiziert ist und **nicht neu hergeleitet werden muss**. - -> **Test ≠ Release.** `project.toml` steht auf `4.0.0-dev` — das ist der laufende -> Entwicklungsstand. Über SMP ausgeliefert wird später die finale, getaggte -> `4.0.0`. Die Testinstallation baut also aus einem Baum, der nicht das Release -> ist, und **muss deshalb ein Wegwerf-FMID benutzen** (`TTST400`). -> -> Warum das kein Detail ist: SMP führt sein Inventar im CDS. Ein Testlauf unter -> `THTP400`, der abbricht, halb angewendet wird oder aus einem `-dev`-Stand -> stammt, hinterlässt genau diese ID als belegt — und das echte 4.0.0 müsste -> dann gegen die eigenen Reste installiert werden. `THTP400` wird erst vom -> getaggten Release vergeben, und zwar genau einmal. +# SMP-Installation httpd — was noch offen ist ---- - -## 1. Fragerunde — vor dem ersten Schritt zu klären - -| # | Frage | Vorschlag | blockiert | -|:--:|---|---|---| -| **F1** | **Wohin installiert SMP die Loadmodule?** Im Repo stehen drei Ziele nebeneinander: `make deploy` landet mangels `[deploy]`-Abschnitt auf `IBMUSER.HTTPD.V4R0M0.LINKLIB`, `samplib/httpd` hat `STEPLIB DD DSN=HTTPD.LINKLIB`, das Konzept schlägt `SYS2.LINKLIB` vor. | **`SYS2.LINKLIB`** — gemessen: APF-autorisiert *und* im LNKLST (§2). Die Proc bräuchte dann keinen STEPLIB mehr, und httpds Selbstautorisierung würde entfallen — **im Experiment beobachten**, s. T6 | JCLIN, DD-Override, Proc-Muster | -| **F2** | **FMID?** Muss 7 Zeichen haben und darf nicht kollidieren. `THTP400` ist im **SMPPTS frei** (1544 SYSMODs geprüft, §2) und passt zur lokalen Konvention. Restrisiko: das **CDS** ist nicht abfragbar, ein längst akzeptiertes SYSMOD könnte dort stehen, ohne im PTS zu sein. | `THTP400` übernehmen; Gewissheit nur über einen SMP-`LIST SYSMODS`-Job | alles | -| **F3** | **HLQ und Volume** für die Produkt-Datasets (DLIB, SAMPLIB, LKLIB)? | `SYS2.HTTPD.*`, Volume wie `MBT_MVS_DEPS_VOLUME` | Allokationsjob | -| ~~F4~~ | ~~ACCEPT mitfahren?~~ **Entschieden: nein, nie.** ACCEPT nimmt `RESTORE` weg und blockiert das erneute Empfangen desselben FMID mit geändertem Inhalt. Begründung und Konsequenzen: `../SMP-COOKBOOK.md` §5.1 | — | — | -| **F5** | **Schreibfreigabe für `mvsdev`** — und ist ein Backup von `SYS1.SMPCDS`/`SMPPTS` vorhanden? | Backup vor dem ersten RECEIVE; Wegwerf-FMID hinterher `REJECT`en | Spike | -| **F6** | **UFS: eigene Disk für `/www`** oder in ein bestehendes Dateisystem mounten? Welcher `UFSDPRMx`-Member? | eigene Disk `HTTPD.WEBROOT`, `MOUNT … PATH(/www) MODE(RO)` | Setup-Job | -| **F7** | **Port für den Test?** Default ist 8080. | 8080, sofern frei | Konfigmuster | -| **F8** | **SAMPLIB: eigenes Produkt-Dataset** (`SYS2.HTTPD.SAMPLIB`) oder in `SYS1.SAMPLIB`? | eigenes — sonst DD-Override-Konflikt mit dem Systemdataset | MCS, Setup-Job | -| **F9** | **Wegwerf-FMID für den Test?** `4.0.0-dev` ist der laufende Entwicklungsstand; über SMP ausgeliefert wird die finale `4.0.0`. Der Test läuft also gegen einen Baum, der **nicht** das Release ist. | **Ja** — Test auf `TTST400`, `THTP400` bleibt für das getaggte 4.0.0 reserviert. Begründung unten. | Spike, Aufräumen | - ---- - -## 2. Was bereits feststeht +**Das Paket wird generiert, nicht mehr von Hand gebaut.** `make package` erzeugt +aus dem `[distribution]`-Block in `project.toml` den SYSMOD, den Allokations- +und den Install-Job. Wie SMP4 dabei arbeitet und warum, steht in +`mbt/scripts/mbt/distribution.py` — dort sind die Handbuchstellen zitiert und +die Messungen vermerkt. Was ein Betreiber tun muss, steht in +[`docs/installation.md`](docs/installation.md). -Nicht neu herleiten, nicht neu messen. Marker wie im Konzeptdokument -(✅ Repo · 🔬 gemessen · 📘 SMP4-Handbuch). +Dieses Dokument hält nur noch das, was **für httpd offen** ist. -**Verfahren** +> *Stand: 2026-08-23, gegen `[distribution]` in `project.toml` abgeglichen.* -- `++MOD(x) LKLIB(ddname)` liefert ein **fertig gebundenes** Loadmodul; ist das - LMOD im JCLIN über einen **IEBCOPY-Step** definiert, kopiert SMP es statt zu - binden. 📘 -- DDNAMEs = letzter Qualifier des Datasetnamens. 📘 -- Copy-Input im JCLIN muss **inline** hinter `//SYSIN DD *` stehen. 📘 -- `SELECT MEMBER=(…)` verwenden — sonst gilt die DLIB als *total* kopiert - (Grenze: zwei Ziel-Bibliotheken). 📘 -- SMP4 kennt **keinen** Datentyp: nur `++MOD/MAC/SRC/MACUPD/SRCUPD/ZAP`. 📘 - -**Zielsystem `mvsdev`** - -- `SMPAPP` und `SMPREC` liegen in **`SYS2.PROCLIB`**, nicht `SYS1.PROCLIB`. 🔬 -- Beide Procs haben genau einen Step (`HMASMP`) 🔬 — **DD-Overrides müssen - trotzdem qualifiziert werden**: `//HMASMP.LINKLIB DD …`, nicht `//LINKLIB DD …`. - Und die Override-Karten müssen **vor** allen hinzugefügten DDs stehen. Siehe - Falle T9; im smptest-Spike gemessen. 🔬 -- Der Proc bringt u. a. `LINKLIB`, `LPALIB`, `PROCLIB`, `PARMLIB`, `SAMPLIB`, - `ASAMPLIB`, `MACLIB`, `CMDLIB` mit — alle auf `SYS1.*`. Wir überschreiben, - was nach `SYS2.*` soll. 🔬 -- `SYS2.LINKLIB` (20 Member) und `SYS2.PARMLIB` (9 Member) existieren. 🔬 - -**Artefaktseite** - -- 6 Loadmodule gebaut: `HTTPD` (AC=1), `HTTPJES2`, `HTTPDM`, `HTTPDMTT`, - `HTTPDSL`, `HTTPDSRV`. ✅ -- `ld370 --pack … -xmit` → `upload_binary` → `RECEIVE` läuft produktiv in - `mbt/scripts/mbtdeploy.py`. ✅ -- `ufsd-utils` ist installiert (`~/go/bin/ufsd-utils`). 🔬 - -**Zielbibliothek `SYS2.LINKLIB`** 🔬 - -Aus `SYS1.PARMLIB` gelesen — beides spricht für `SYS2.LINKLIB` als Ziel: +> **Die frühere Fassung verwies auf `../SMP-COOKBOOK.md` und +> `../SMP-INSTALLATION.md`. Beide Dateien gibt es nicht mehr.** Der Spike liegt +> noch in [`../smptest`](../smptest) — er hat 2026-08-08 gezeigt, dass SMP das +> LKLIB-Modul *kopiert* statt es neu zu binden, und genau darauf baut das +> generierte Paket auf. -``` -IEAAPF00: SYS2.LINKLIB MVS000, USER BATCH LINKLIB <- APF-autorisiert -LNKLST00: SYS2.LINKLIB, USER LOAD MODULE LIBRARY <- im Linklist -IEABLD00: nur SYS1.LINKLIB-Module (HEWL, IFOXxx, LOGON …) <- kein BLDL-Eintrag -``` +--- -- **APF:** `SYS2.LINKLIB` ist autorisiert. httpd bringt sich heute selbst in den - autorisierten Zustand (T6); von dort aus wäre es das von Anfang an. ✔ -- **LNKLST:** die Module werden ohne STEPLIB gefunden. ✔ -- **Kein IPL nötig**, damit ein *neues Member* sichtbar wird — in der residenten - BLDL-Liste (`IEABLD00`) steht nichts aus `SYS2.LINKLIB`. Vorsicht dagegen beim - **Erweitern oder Komprimieren** eines LNKLST-Datasets im laufenden Betrieb; - ausreichend Platz vorher einplanen. - -**SYSMOD-Inventar des Zielsystems** 🔬 - -`SYS1.SMPPTS` ist über die REST-API auslesbar — die Membernamen der MCS-Entries -sind **nicht** encodiert (dokumentierte Ausnahme 📘: *„With the exception of the -MCS entry in the SMPPTS dataset, these member names are encoded and cannot be -easily accessed by utilities other than SMP."*). - -- **1544 SYSMODs** liegen im PTS. Darunter die Funktions-SYSMODs des Sysgens: - `TIST801`, `TJES801`, `TMVS804`, `TMVS816`, `TMVS817`, `TNIP800`, `TTSO801` — - also dieselbe Form `T` + 3 Buchstaben + 3 Ziffern, die wir vorschlagen. -- Ebenfalls da: `RAK0001` (RAKFs Usermod). **`TRKF200` dagegen nicht** — RAKF 2.0 - als Funktion ist auf diesem System nicht empfangen. -- **Frei im PTS:** `THTP400`, `TTST400`, `TUFS100`, `TFTP100`, `TLBC100`. -- ⚠ **`TMVS100` für mvsmf nicht verwenden** — `TMVS8xx` sind die - MVS-Funktions-SYSMODs des Sysgens. Vorschlag stattdessen: `TZMF100`. - -**Das CDS ist so *nicht* prüfbar.** Seine Membernamen sind echte Hashes -(Stichprobe: `Ak\x7F\x1C]\x0D\xB6\x00`, `Jj7\x96\xFF\xDB\x3A\x00`) — ein Namensvergleich dort -liefert nur Scheinergebnisse. Für Gewissheit braucht es einen SMP-`LIST`-Job. -Ebenso: `list_members()` scheitert an beiden Datasets, weil mvsMF die -Steuerzeichen als ungültiges JSON ausliefert; der Roh-Request unten umgeht das. - -```python -# PTS-Inventar auslesen (read-only) -import re, base64, urllib.request -url = "http://:/zosmf/restfiles/ds/SYS1.SMPPTS/member" -req = urllib.request.Request(url) -req.add_header("Authorization", "Basic " + base64.b64encode(b"user:pass").decode()) -req.add_header("Accept", "application/json") -txt = urllib.request.urlopen(req, timeout=90).read().decode("utf-8", "replace") -ids = sorted({n.strip() for n in re.findall(r'"member"\s*:\s*"(.*?)"', txt) - if "\\u" not in n}) # MCS-Entries = lesbare SYSMOD-IDs -``` +## 1. Offen ---- +### O1 — `THTP400` im CDS und ACDS prüfen · **vor dem 4.0.0-Tag** -## 3. TODO — Spike (P0, zuerst) - -> **Erledigt.** Der Spike wurde am 2026-08-08 im Projekt -> [`../smptest`](../smptest) gefahren, nicht mit `HTTPDM` — ein Modul, keine -> Abhängigkeiten, eigener FMID `TSMP100`. Ergebnis: SMP **kopiert** das -> LKLIB-Modul, `SYS2.CMDLIB(SMPTEST)` ist byteidentisch mit `build/SMPTEST`, -> ACCEPT trägt es in die DLIB, RESTORE nimmt es zurück. Belege und -> wiederverwendbare JCL in `../smptest/jcl/` und `../smptest/scripts/`. -> -> Für httpd bleibt davon: der Weg ist bestätigt, die Schritte unten sind die -> Vorlage für den ersten httpd-Lauf. - -Die ursprüngliche Fragestellung: **kopiert SMP das LKLIB-Modul wirklich -unverändert?** Braucht **kein** neues mbt-Feature — alles von Hand, mit den -vorhandenen Upload-Wegen. - -- [ ] **S1** `make modules` — Stand sicherstellen -- [ ] **S2** LKLIB auf MVS bringen — **Weg A (XMIT)**, der heute implementierte - Pfad (§10.4 im Konzeptdokument): - - ```sh - ld370 --pack build/HTTPDM.iebcopy -o build/httpd.deploy \ - -xmit --dsn HTTPD.V4R0M0.LKLIB - # -> upload_binary (FB80) -> TSO RECEIVE -> HTTPD.V4R0M0.LKLIB - ``` - - `ld370 --pack` erhält dabei die Attribute **jedes** Members (AC, RENT, - REUS) aus dem Bindelauf 📖 — deshalb überlebt `HTTPD`s `AC=1` den Transport. - `--blocksize` muss beim Binden und Packen identisch sein (Default 15040). - RECEIVE mergt nicht: Zielbibliothek vorher löschen, wie `mbtdeploy` es tut. - *Alternative für später:* `-iebcopy` + Batch-`IEBCOPY` statt TSO — Vorteile - und offene Fragen in §10.4. -- [ ] **S3** DLIB + SAMPLIB allokieren (IEFBR14): `SYS2.HTTPD.AHTTPLOD` als - Loadlibrary (DCB wie `SYS2.LINKLIB`) -- [ ] **S4** MCS-Datei von Hand schreiben (~12 Zeilen) und als FB80 hochladen: +Belegt ist bisher nur der **SMPPTS** auf `mvsdev`: 1544 SYSMODs gelesen, kein +`THTP400` (§3). Der PTS zeigt aber nur, was *empfangen* wurde. CDS und ACDS +speichern gehashte Membernamen — ein Namensvergleich dort liefert +Scheinergebnisse, wie in §3 gemessen. Gewissheit gibt nur ein `LIST`-Job, auf +**beiden** Ständen (`mvsdev` = MVS/CE, `drnmig3a` = TK5): ``` -++FUNCTION(TTST400) . -++VER(Z038) /* httpd 4.0.0-dev - SPIKE, Wegwerf-FMID */ . -++JCLIN . -//TTST400 JOB 1,'HTTPD SPIKE',MSGLEVEL=1,CLASS=A -//COPYLOAD EXEC PGM=IEBCOPY -//AHTTPLOD DD DISP=SHR,DSN=SYS2.HTTPD.AHTTPLOD -//LINKLIB DD DISP=SHR,DSN=SYS2.LINKLIB -//SYSIN DD * - COPY INDD=AHTTPLOD,OUTDD=LINKLIB - SELECT MEMBER=(HTTPDM) +//LIST EXEC SMPAPP +//SMPCNTL DD * + LIST CDS SYSMOD(THTP400) . + LIST ACDS SYSMOD(THTP400) . /* -++MOD(HTTPDM) LKLIB(HTTPLOAD) DISTLIB(AHTTPLOD) . ``` -- [ ] **S5** Install-Job von Hand: `RECEIVE SELECT(TTST400)` → - `APPLY S(TTST400) CHECK` → `APPLY S(TTST400) DIS(WRITE)`, mit - `//SMPPTFIN DD DSN=…`, `//HTTPLOAD DD …LKLIB`, `//AHTTPLOD DD …`, - `//LINKLIB DD DISP=SHR,DSN=SYS2.LINKLIB` -- [ ] **S6** **Bitvergleich** `SYS2.LINKLIB(HTTPDM)` gegen `build/HTTPDM` — - *das ist der eigentliche Test.* Gleich ⇒ SMP hat kopiert, nicht gebunden, - und `norent`/`ac`/Entry stammen unverändert aus ld370. -- [ ] **S7** `ACCEPT S(TTST400) DIS(WRITE)` → landet das Modul in `AHTTPLOD`? -- [ ] **S8** `++PTF` mit demselben Modul, danach `RESTORE` — kommt der Vorstand - sauber zurück? -- [ ] **S9** Aufräumen: `RESTORE` → `REJECT SELECT(TTST400)`, Test-Datasets - löschen. **Kontrollieren, dass `THTP400` im CDS unberührt ist** — es wird - erst vom getaggten 4.0.0 vergeben. - -**Abbruchkriterium:** Wenn S6 zeigt, dass SMP doch bindet, stoppen und auf das -RAKF-Muster wechseln (Anhang C.7 im Konzeptdokument) — nicht auf Objektdecks. - ---- - -## 4. TODO — SMP-Paket für httpd +**RC 04 mit leerer Liste heißt frei.** Der Zonenoperand ist Pflicht; bares +`LIST SYSMODS .` ist SMP/E-Syntax und endet in `HMA2033 SYNTAX ERROR`. Und +qualifizieren: `LIST CDS .` gibt auf MVS/CE 116 000 Zeilen aus. -Erst wenn §3 grün ist. +Die FMID wird genau einmal vergeben. ufsd (`TUFS120`) und ftpd (`TFTP100`) +haben diesen Job vor ihrem Tag gefahren, httpd noch nicht — der Kommentar in +`project.toml` sagt das auch so. -- [ ] **P1** FMID final vergeben (F2) und in `knowledge/` dokumentieren — - `THTP400` **erst mit dem getaggten 4.0.0**, nicht aus dem `-dev`-Baum -- [ ] **P2** `[smp]`-Abschnitt in `project.toml`: +### O2 — Testinstallation mit Wegwerf-FMID `TTST400` -```toml -[smp] -fmid = "THTP400" -system = "Z038" -mode = "lklib" -lklib = "HTTPLOAD" # DDNAME der hochgeladenen Loadlibrary -distlib = "AHTTPLOD" # DDNAME der Loadmodul-DLIB -samplib = "AHTTPSAM" # DDNAME der SAMPLIB-DLIB -target = "SYS2.LINKLIB" # aus F1 -prereq = ["TUFS100"] # sonst aus [dependencies] abgeleitet -``` +Die Generalprobe aus einem `-dev`-Baum. Ein Testlauf unter `THTP400`, der +abbricht oder halb angewendet wird, belegt genau die ID, die das getaggte 4.0.0 +braucht — und das CDS lässt sich hinterher nur mit `UCLIN` bereinigen +(`docs/installation.md` §11). -- [ ] **P3** MCS-Generator: `++FUNCTION`/`++VER`/`++JCLIN` + je `[[module]]` ein - `++MOD … LKLIB` + je SAMPLIB-Member ein `++MAC` -- [ ] **P4** COPY-JCLIN-Generator: `SELECT MEMBER=(…)` aus den - `[[module]]`-Namen -- [ ] **P5** Allokationsjob generieren (DLIB, SAMPLIB, ASAMPLIB, LKLIB) -- [ ] **P6** `make smppkg` → `dist/httpd-4.0.0.smpmcs` + `…lklib.xmit` + - `…-inst.jcl` + `…-setup.jcl` -- [ ] **P7** `make smpinst` — Upload + Job absetzen + RC prüfen (**schreibt auf MVS**) -- [ ] **P8** Alle 6 Module statt nur `HTTPDM`; `HTTPD` trägt **AC=1** — prüfen, - dass die Autorisierung den Kopiervorgang übersteht -- [ ] **P9** `++PTF`-Pfad (`make smpptf`) — **ganzes** LMOD via LKLIB -- [ ] **P10** **Modul entfällt / kommt hinzu:** Wenn sich die Modulliste ändert, - braucht der SYSMOD ein neues `++JCLIN` mit angepasster - `SELECT MEMBER=(…)`-Liste; ein entfallenes Modul zusätzlich per - `++MOD(x) DELETE`. Generator muss das aus dem Diff der `[[module]]`-Namen - gegen den letzten Release ableiten. -- [ ] **P11** **Aliase:** httpd hat heute keine. Falls je welche entstehen, - müssen sie mit `TALIAS(…)` deklariert werden **und** in der LKLIB - vorhanden sein — sonst kopiert SMP sie nicht 📘. +Mit mbt ist das eine Zeile: `fmid` in `project.toml` auf `TTST400` setzen, +`make package`, installieren — **und die Änderung nie committen**. ---- +Die Datasetnamen kollidieren dabei nicht mit dem späteren Release, ohne dass +man etwas dafür tun muss: `@VRM@` kommt aus der Projektversion, und +`4.0.0-dev` ergibt `V4R0M0D`, das getaggte `4.0.0` dagegen `V4R0M0`. Der Test +lebt also in `HTTPD.V4R0M0D.*`, das Release in `HTTPD.V4R0M0.*`. -## 5. TODO — SAMPLIB +Aufräumen danach: UCLIN-Job aus `docs/installation.md` §11 mit `TTST400`, dann +die Datasets löschen, dann `LIST CDS/ACDS SYSMOD(THTP400)` — das ist zugleich +O1. -Siehe §14.5 im Konzeptdokument. Kernregel: +### O3 — UFS-Webroot: SMP kann das nicht ausliefern -> **Produkt besitzt die Muster, Site besitzt die Kopien.** -> `SYS2.HTTPD.SAMPLIB(HTTPD)` gehört SMP — `SYS2.PROCLIB(HTTPD)` nicht. +Eine UFS-Disk ist ein `DSORG=PS`, `RECFM=U`, `BLKSIZE=4096`-Binärimage; SMP4 +kennt dafür keinen Elementtyp (es kennt nur +`++MOD/MAC/SRC/MACUPD/SRCUPD/ZAP`). Sie ist außerdem **Site-Inhalt** — ein +erneutes APPLY dürfte sie nie anfassen. -Grund: `samplib/httpd` enthält `STEPLIB`, `VOL=SER=MVS000`, REGION, Port — alles -Werte, die der Betreiber ändert. Besäße SMP die aktive Proc, wäre jede Anpassung -beim nächsten APPLY weg. +Heute steht in `docs/installation.md`, dass ohne UFSD nur die `MOD=`-Routen +laufen und `HTTPD044W` kommt. Das ist ehrlich, aber es ist keine Auslieferung. +Offen: -- [ ] **L1** `SYS2.HTTPD.SAMPLIB` + `.ASAMPLIB` allokieren (FB80) -- [ ] **L2** Bestehende Muster als `++MAC` aufnehmen: - `samplib/httpd` → Member `HTTPD`, `samplib/httpprm0` → Member `HTTPPRM0` -- [ ] **L3** **Generierte** Member ergänzen — sie tragen FMID, Version und - Datasetnamen und müssen zum Release passen: - - `HTTPINST` — der SMP-Install-Job - - `HTTPSETU` — der Setup-Job (Disk, Mount, Kopien) - - `HTTPWEB` — JCL-Muster für den Disk-Upload -- [ ] **L4** DD-Override im APPLY/ACCEPT-Step: - `//SAMPLIB DD DISP=SHR,DSN=SYS2.HTTPD.SAMPLIB` (letzter Qualifier passt) -- [ ] **L5** Kopierschritt **im Setup-Job**, nicht im Install-Job: +- [ ] **U1** Image bauen — `ufsd-utils create webroot.img --size 10M`, + `ufsd-utils cp -r static/ webroot.img:/`, danach `ufsd-utils ls -l` + gegenprüfen (Falle T3) +- [ ] **U2** Hochladen: `ufsd-utils upload webroot.img --dsn HTTPD.WEBROOT` +- [ ] **U3** Mount dokumentieren — `UFSDPRMx` gehört **ufsd**, nicht httpd: + `MOUNT DSN(HTTPD.WEBROOT) PATH(/www) MODE(RO)`, oder dynamisch + `/F UFSD,MOUNT DSN=HTTPD.WEBROOT,PATH=/www,MODE=RO`. Kein `++MACUPD` in + ufsds Parmlib +- [ ] **U4** Reihenfolge: **ufsd zuerst**, Dateisystem gemountet, `/www` + existiert — *dann* httpd. Eine Laufzeitabhängigkeit, die SMP nicht + abbilden kann +- [ ] **U5** `make webroot` + CI-Asset `httpd--webroot.img`, mit + SHA256 statt eines Reproduzierbarkeitsversprechens +- [ ] **U6** **Update-Verhalten festlegen** — `.SAMPLE`-Name oder Existenzprüfung. + Ein `ufsd-utils upload --replace` im Update-Job wäre Datenverlust beim + Betreiber + +`[distribution] extra = [...]` kann eine Datei ins Archiv legen, ohne SMP zu +behelligen — das ist der wahrscheinliche Weg für U5, sobald U6 entschieden ist. + +### O4 — Setup-Job: ausliefern oder Handarbeit lassen? + +`docs/installation.md` §7 lässt den Betreiber Proc und Konfigmember von Hand aus +der SAMPLIB kopieren. Das ist Absicht — *Produkt besitzt die Muster, Site +besitzt die Kopien* — aber ein **Muster** für den Kopierschritt wäre trotzdem +freundlicher als eine Prosaanweisung: ```jcl //COPYPROC EXEC PGM=IEBCOPY -//IN DD DISP=SHR,DSN=SYS2.HTTPD.SAMPLIB +//IN DD DISP=SHR,DSN=HTTPD.@VRM@.SAMPLIB //OUTP DD DISP=SHR,DSN=SYS2.PROCLIB //OUTM DD DISP=SHR,DSN=SYS2.PARMLIB //SYSIN DD * @@ -282,145 +115,157 @@ beim nächsten APPLY weg. /* ``` -- [ ] **L6** Für die Testinstallation eine **eigene Minimalkonfiguration** - erzeugen — siehe Falle T4 +Als weiteres SAMPLIB-Member (`HTTPSETU`) wäre das ein Zweizeiler in +`samplib/` — mit dem Haken, dass `@VRM@` dort ersetzt wird, `SYS2.PROCLIB` und +`SYS2.PARMLIB` aber geraten sind und auf TK5 falsch. Entscheidung offen. +Weder ufsd noch ftpd liefern so etwas aus. --- -## 6. TODO — UFS-Disk / WWW-Root +## 2. Erledigt — was mbt heute übernimmt + +Nicht neu planen. Die frühere §3 (Spike), §4 (SMP-Paket), §5 (SAMPLIB) sind +abgearbeitet oder ersetzt: + +| Früher offen | Heute | +|---|---| +| Spike: kopiert SMP wirklich? | ✅ 2026-08-08 in `../smptest` bewiesen (`TSMP100`, Bitvergleich) | +| MCS-/JCLIN-/Allokationsjob-Generator | ✅ `mbt/scripts/mbt/distribution.py` + `mbtdist.py` | +| `[smp]`-Block in `project.toml` | ✅ als `[distribution]` / `[distribution.smp]`, mit **Datasetnamen** statt DDNAMEs — der DDNAME ist immer der letzte Qualifier | +| SAMPLIB als `++MAC` in den SYSMOD | ❌ verworfen: eine MCS-Karte endet in Spalte 72, `HTTPPRM0` hat Kommentarzeilen bis 80. Die SAMPLIB fährt als eigenes XMIT per TSO RECEIVE, außerhalb von SMP | +| Install-Job als SAMPLIB-Member | ❌ liegt im Archiv (`httpd--inst.jcl`), nicht in der SAMPLIB | + +**Umgekehrt entschieden gegenüber der alten Fassung — zwei Punkte:** + +- **Ziel ist `HTTPD.@VRM@.LINKLIB`, nicht `SYS2.LINKLIB`** (alte F1). Versionierte + Produktdatasets heißen: kein IPL für einen APF-Eintrag, keine Kollision mit + Systembibliotheken, jede Release-Stufe nebeneinander installierbar. Die Proc + behält ihren STEPLIB und zieht ihn über `@LINKLIB@` aus dem Paket. + Konsequenz für die alte Falle T6: der Selbstautorisierungsweg über SVC 244 + bleibt der Normalfall, `HTTPD002I AUTHORIZED BY SVC (MODULE KEY 8)` ist die + erwartete Zeile. Der APF-Zweig ist trotzdem beschrieben — ein Betreiber, der + die LINKLIB in `IEAAPF00` einträgt, bekommt `AUTHORIZED BY LIBRARY (MODULE + KEY 0)`, und `docs/installation.md` §2 sagt, was das für die Modulspeicherung + bedeutet. +- **ACCEPT fährt mit** (alte F4 sagte „nein, nie"). Der ACCEPT füllt die DLIB + und ist damit die Basis, auf die ein späteres `RESTORE` eines **PTF** + zurückgeht — ohne ihn würde RESTORE das Modul löschen statt es + zurückzunehmen. Der Preis ist, dass die FMID selbst permanent wird: `RESTORE` + scheitert, weil akzeptiert, und `REJECT`, weil der ACCEPT die MCS aus dem + SMPPTS entfernt. Der Weg zurück ist `UCLIN`, beschrieben in + `docs/installation.md` §11. **Service (PTFs) wird weiterhin nie akzeptiert.** -Siehe §14.1–§14.4 im Konzeptdokument. SMP4 kann das **nicht** ausliefern: eine -UFS-Disk ist ein `DSORG=PS`, `RECFM=U`, `BLKSIZE=4096`-Binärimage, und es gibt -keinen passenden Elementtyp. Sie ist außerdem **Site-Inhalt** — ein erneutes -APPLY dürfte sie nie anfassen. +--- -- [ ] **U1** Image bauen: +## 3. Verifiziertes Inventar -```sh -ufsd-utils create webroot.img --size 10M -ufsd-utils cp -r static/ webroot.img:/ -ufsd-utils ls -l webroot.img:/ # Kontrolle, s. Falle T3 -``` +Nicht neu messen (🔬 gemessen · 📘 SMP4-Handbuch · ✅ Repo). -- [ ] **U2** Hochladen: `ufsd-utils upload webroot.img --dsn HTTPD.WEBROOT` - (legt das Dataset mit an) -- [ ] **U3** Mount eintragen — **`UFSDPRMx` gehört ufsd, nicht httpd** (F6): - `MOUNT DSN(HTTPD.WEBROOT) PATH(/www) MODE(RO)` - oder dynamisch `/F UFSD,MOUNT DSN=HTTPD.WEBROOT,PATH=/www,MODE=RO`. - **Kein `++MACUPD` in ufsds Parmlib** — Muster ausliefern, Schritt - dokumentieren. -- [ ] **U4** Laufzeitreihenfolge sicherstellen: **ufsd zuerst starten**, - Dateisystem gemountet, `/www` existiert — *dann* httpd. `DOCROOT` ist eine - Laufzeitabhängigkeit, die SMP nicht abbilden kann. -- [ ] **U5** `make webroot` + CI-Asset `httpd-4.0.0-webroot.img` (§20 im Konzeptdokument), mit SHA256-Summe statt Reproduzierbarkeitsversprechen -- [ ] **U6** **Update-Verhalten festlegen** (offen): `.SAMPLE`-Name oder - Existenzprüfung im Setup-Job. `ufsd-utils upload --replace` in einem - Update-Job wäre ein Datenverlust beim Betreiber. +**Verfahren** 📘 + +- `++MOD(x) LKLIB(ddname)` liefert ein **fertig gebundenes** Loadmodul; ist das + LMOD im JCLIN über einen IEBCOPY-Step definiert, kopiert SMP es statt zu binden. +- DDNAME = letzter Qualifier des Datasetnamens. +- Copy-Input im JCLIN muss **inline** hinter `//SYSIN DD *` stehen. +- `SELECT MEMBER=(…)` verwenden — sonst gilt die DLIB als *total* kopiert. +- SMP4 kennt keinen Datentyp: nur `++MOD/MAC/SRC/MACUPD/SRCUPD/ZAP`. + +**Zielsystem `mvsdev`** 🔬 + +- `SMPAPP` und `SMPREC` liegen in `SYS2.PROCLIB`, nicht `SYS1.PROCLIB`. +- Beide Procs haben genau einen Step (`HMASMP`); DD-Overrides müssen ihn + trotzdem als Qualifier tragen. Siehe Falle T9. +- Der Proc bringt `LINKLIB`, `LPALIB`, `PROCLIB`, `PARMLIB`, `SAMPLIB`, + `ASAMPLIB`, `MACLIB`, `CMDLIB` mit — alle auf `SYS1.*`. + +**SYSMOD-Inventar** 🔬 — `SYS1.SMPPTS` ist auslesbar, weil die MCS-Entries als +einzige *nicht* encodiert sind (dokumentierte Ausnahme 📘). 1544 SYSMODs im PTS, +darunter die Funktions-SYSMODs des Sysgens. **Frei im PTS:** `THTP400`, +`TTST400`. Das **CDS ist so nicht prüfbar** — Stichprobe der Membernamen: +`Ak\x7F\x1C]\x0D\xB6\x00`, `Jj7\x96\xFF\xDB\x3A\x00`. Deshalb O1. + +> ⚠ Die alte Fassung nannte hier `TMVS100` als Vorschlag für mvsmf und riet +> davon ab. Der ökosystemweite Beschluss steht inzwischen im Root-`CLAUDE.md`: +> **nie `TMVS…`** (MVS/CE führt USERMODs `TMVS804/816/817`), mvsmf bekommt +> `TZMF010`. + +**Artefaktseite** ✅ — **5** Loadmodule: `HTTPD` (AC=1), `HTTPDSRV`, `HTTPDM`, +`HTTPDMTT`, `ABEND0C1`. Die alte Fassung nannte sechs mit `HTTPJES2` und +`HTTPDSL`; beide sind seit 4.0.0 nicht mehr gebaut (mvsMFs jobs- und +dataset-API ersetzen sie, Quellen liegen in `tbd/`). --- -## 7. Fallen +## 4. Fallen -Jede einzelne kostet sonst einen Arbeitstag. +Die, die noch gelten. -- **T1 — Die eiserne Regel für COPY-LMODs.** Ein Update liefert **immer das - ganze Loadmodul** über LKLIB nach. Ein einzelnes Objekt-`++MOD` gegen ein - COPY-LMOD bindet SMP *allein* und zerstört das Modul (📘 „no INCLUDE for the - current version"). Nie ein Objektdeck in ein `++PTF` für httpd. +- **T1 — Die eiserne Regel für COPY-LMODs.** Ein Update liefert **immer das ganze + Loadmodul** über LKLIB nach. Ein einzelnes Objekt-`++MOD` gegen ein COPY-LMOD + bindet SMP allein und zerstört das Modul (📘 „no INCLUDE for the current + version"). Nie ein Objektdeck in ein `++PTF` für httpd. -- **T2 — `norent` / `ac` bleiben bei ld370.** Der Grund, warum wir auf dem Host - binden: ld370s Template markiert alles RENT+REUS, C-Module mit mutable statics - nehmen dann bei TSO-Load einen S0C4 (dokumentiert in RAKFs - `APPLICATIONS/project.toml`). Wenn ein JCLIN-Bindeschritt entsteht, wo keiner - sein sollte, ist der Fehler *hier*. +- **T2 — `norent` / `ac` bleiben bei ld370.** Der Grund, warum auf dem Host + gebunden wird. Entsteht irgendwo ein JCLIN-Bindeschritt, wo keiner sein + sollte, ist der Fehler hier. - **T3 — ASCII→EBCDIC hängt an der Dateiendung.** `ufsd-utils cp` konvertiert - nur bei bekannter Endung (`.html`, `.css`, `.js`, …). Eine Datei ohne Endung - oder mit `.tmpl` landet **verbatim als ASCII** in der Disk und ist auf MVS - unlesbar — ohne Fehlermeldung. `-t` erzwingt Konvertierung, `-b` erzwingt - binär. Ausgabe von `ufsd-utils ls -l` gegenprüfen. - -- **T4 — Das ausgelieferte `httpprm0` aktiviert nur MVSMF-Routen.** Die einzigen - unkommentierten Zeilen im Muster sind `MOD=MVSMF /zosmf/…`. Für eine - httpd-Testinstallation **ohne** mvsmf ist das die falsche Konfiguration — - eigene Minimalkonfiguration mit `DOCROOT=/www` und ggf. `MOD=HTTPDSRV /.dsrv` - verwenden. - -- **T5 — mvsMF wirft `S80A ABEND` nach wenigen Requests.** Ein HTTP 503 heißt - dann **nicht** „Dataset fehlt". Außerdem liefern `dataset_exists()` und - `list_datasets()` gegen diesen Server durchgehend `False`/`[]` — auch für - nachweislich existierende Datasets. Verlässlich ist nur `list_members()`. - Existenzprüfungen im Setup-Job besser per JCL (`IEFBR14`/`IDCAMS LISTCAT`). - -- **T9 — DD-Overrides brauchen den Proc-Step UND die richtige Reihenfolge.** - Im smptest-Spike zweimal reingelaufen 🔬. `//CMDLIB DD DSN=SYS2.CMDLIB` nach - `EXEC SMPAPP` ist **kein** Override, sondern eine zweite DD gleichen Namens: - beide Datasets werden allokiert, SMP nimmt die des Procs, das Modul landet in - `SYS1.CMDLIB` — und jede SMP-Meldung sagt weiterhin `LIBRARY=CMDLIB`, der - Fehler ist also aus dem Log **nicht** ablesbar. Qualifizieren allein reicht - auch nicht: stehen hinzugefügte DDs (`SMPTLOAD`, `ASMPTEST`) vor der - Override-Karte, wird sie ebenfalls ignoriert. Richtig ist: - **erst alle Overrides, dann alle Ergänzungen**, alle mit `HMASMP.`-Präfix. - Kontrolle: nachsehen, wo das Member wirklich liegt — nicht dem RC glauben. - -- **T6 — Die Autorisierung ändert ihren Weg, und das will beobachtet werden.** - httpd hängt heute *nicht* davon ab, dass die STEPLIB autorisiert ist — es - **autorisiert sich selbst**. `httpd.c` verzweigt beim Start ✅: - - ```c - if (crt->crtopts & CRTOPTS_AUTH) rc = auth_setup(argv[0]); /* schon autorisiert */ - else rc = unauth_setup(argv[0]); /* holt sich die Autorisierung */ - ``` - - `unauth_setup()` ruft `__autask()` (SVC 244 → JSCBAUTH) und danach - `__austep()`, um die STEPLIB nachträglich APF-autorisiert zu machen — - Meldungen `HTTPD011I … via SVC 244` und `HTTPD013I STEPLIB is now APF - authorized`. Deshalb funktioniert die heutige Proc mit - `STEPLIB DD DSN=HTTPD.LINKLIB` auch ohne APF-Eintrag. - - Nach einer Installation in die autorisierte LNKLST-Verkettung sollte der - `auth_setup()`-Zweig greifen (`HTTPD010I … is APF authorized`) und die ganze - Selbstautorisierung entfallen. **Das ist während der Installationsexperimente - empirisch zu prüfen**, nicht vorher zu behaupten: - - - Welcher Zweig wird tatsächlich genommen? (Meldung im Log: `HTTPD010I` vs. - `HTTPD011I`/`HTTPD013I`) - - Ist `__austep()` dann überflüssig, harmlos oder störend? - - Braucht es eine zusätzliche Prüfung im Code — oder reicht `CRTOPTS_AUTH` - bereits? Der Verdacht ist, dass es schon reicht. - - Nebenbefund: SVC 244 kommt von RAKFs Usermod `RAK0001` — der liegt auf - `mvsdev` im PTS 🔬. Der heutige Selbstautorisierungsweg hängt also an RAKF. - **Kommt nach dem Spike, blockiert ihn nicht.** - -- **T7 — DDNAME = letzter Qualifier.** `SYS2.HTTPD.LINKLIB` hätte ebenfalls den - DDNAME `LINKLIB` — die Kollision mit dem Proc-DD verschwindet nicht durch - Umbenennen. Override ist der Weg. - -- **T8 — `ACCEPT` ohne `COND`.** RAKF macht das und akzeptiert damit auch nach - einem gescheiterten APPLY. Getrennte Jobs (F4). + nur bei bekannter Endung. Eine Datei ohne Endung oder mit `.tmpl` landet + **verbatim als ASCII** in der Disk und ist auf MVS unlesbar — ohne + Fehlermeldung. `-t` erzwingt Konvertierung, `-b` binär. Betrifft O3. + +- **T4 — Das ausgelieferte `httpprm0` aktiviert nur MVSMF-Routen.** Für eine + Testinstallation *ohne* mvsmf ist das die falsche Konfiguration. + `docs/installation.md` §7 sagt das jetzt auch dem Betreiber; für den Test + reicht eine eigene Minimalkonfiguration mit `DOCROOT=/www`. + +- **T7 — DDNAME = letzter Qualifier.** `HTTPD.@VRM@.LINKLIB` hat den DDNAME + `LINKLIB` und kollidiert damit zwangsläufig mit dem Proc-DD. Umbenennen hilft + nicht, Override ist der Weg — mbt kennt die Proc-DDs (`SMPAPP_PROC_DDS`) und + schreibt die Overrides selbst. + +- **T9 — DD-Overrides brauchen den Proc-Step UND die richtige Reihenfolge.** Im + Spike zweimal reingelaufen 🔬: `//LINKLIB DD …` nach `EXEC SMPAPP` ist **kein** + Override, sondern eine zweite DD gleichen Namens — beide Datasets werden + allokiert, SMP nimmt die des Procs, und jede Meldung sagt weiterhin + `LIBRARY=LINKLIB`. Aus dem Log ist der Fehler nicht ablesbar. Richtig: erst + alle Overrides, dann alle Ergänzungen, alle mit `HMASMP.`-Präfix. Der + generierte Job macht das; der Kommentar im Job sagt auch, dass man ihn nicht + umsortieren soll. + +**Erledigt, nur zur Erinnerung warum:** + +- ~~**T8 — `ACCEPT` ohne `COND`.**~~ Der generierte Job hängt jeden SMP-Step an + den vorigen: `ACCEPT EXEC SMPAPP,COND=(0,NE,APPLY.HMASMP)`. +- ~~**T5 — mvsMF `S80A` nach wenigen Requests.**~~ Aus der Zeit vor dem + Storage-Reclaim (#154/#174). Nicht als aktueller Befund weiterreichen; wenn + ein Setup-Job Existenzprüfungen braucht, sind `IEFBR14`/`IDCAMS LISTCAT` + trotzdem der robustere Weg. --- -## 8. Definition of Done — Testinstallation - -- [ ] `RECEIVE` / `APPLY` laufen mit RC ≤ 4, `APPLY CHECK` vorher sauber -- [ ] Alle 6 Module liegen in der Zielbibliothek und sind **bitgleich** mit - `build/` -- [ ] `SYS2.HTTPD.SAMPLIB` enthält `HTTPD`, `HTTPPRM0`, `HTTPINST`, `HTTPSETU`, - `HTTPWEB` -- [ ] Setup-Job hat Proc und Konfig nach `SYS2.PROCLIB`/`SYS2.PARMLIB` kopiert -- [ ] `HTTPD.WEBROOT` ist angelegt, unter `/www` gemountet, `index.html` darin - lesbar (EBCDIC!) -- [ ] `/S HTTPD` startet, `curl http://mvsdev:8080/` liefert `index.html` -- [ ] `RESTORE` bringt einen sauberen Vorstand zurück -- [ ] Wegwerf-FMID `TTST400` ist `REJECT`ed, Testdatasets sind gelöscht -- [ ] `THTP400` ist im CDS **nicht** belegt — reserviert für das getaggte 4.0.0 +## 5. Definition of Done — Testinstallation + +- [ ] `RECEIVE` / `APPLY` mit RC ≤ 4, `APPLY CHECK` vorher sauber +- [ ] **Fünf** `HMA2380 COPY SUCCESSFUL`-Zeilen — eine je Modul. Weniger fällt + nicht auf: der APPLY endet trotzdem RC 00 +- [ ] Alle fünf Module liegen in `HTTPD.V4R0M0D.LINKLIB` und sind **bitgleich** + mit `build/` +- [ ] `HTTPD.V4R0M0D.SAMPLIB` enthält `HTTPD` und `HTTPPRM0`, und der `STEPLIB` + im Member zeigt auf `HTTPD.V4R0M0D.LINKLIB` (die `@LINKLIB@`-Ersetzung) +- [ ] `/S HTTPD` startet bis `HTTPD001I … READY`, `HTTPD002I` sagt, über welchen + Weg autorisiert wurde +- [ ] `HTTPD.WEBROOT` angelegt, unter `/www` gemountet, `index.html` in EBCDIC + lesbar — **nur wenn O3 bis dahin steht**; sonst gegen eine `MOD=`-Route + prüfen und `HTTPD044W` als erwartet abhaken +- [ ] `curl http://mvsdev:8080/…` antwortet +- [ ] Aufräumen: UCLIN auf `TTST400`, Testdatasets gelöscht, `LIST CDS/ACDS + SYSMOD(THTP400)` antwortet RC 04 mit leerer Liste --- -## 9. Nicht Teil der Testinstallation +## 6. Nicht Teil davon -- Ausrollen auf ufsd, ftpd, mvsmf (dieselbe Mechanik, §21 Roadmap im Konzeptdokument) -- CI-Integration der Artefaktmatrix (§20 im Konzeptdokument) -- Objektdeck-Auslieferung — **verworfen**, Begründung in Anhang C +- Ausrollen auf ufsd, ftpd, mvsmf — ufsd und ftpd sind bereits umgestellt und + sind die Referenz, an der httpds `[distribution]` sich orientiert. +- Objektdeck-Auslieferung — verworfen, siehe T1/T2. From adcb9378c91f0e0e38e6fecbd468df38f190e81c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 08:05:35 +0200 Subject: [PATCH 03/11] Update index.html --- static/index.html | 183 +++++++++++++++++++++++++++++----------------- 1 file changed, 116 insertions(+), 67 deletions(-) diff --git a/static/index.html b/static/index.html index e700072..1e08b6e 100644 --- a/static/index.html +++ b/static/index.html @@ -1,93 +1,142 @@ - - - HTTPD 4.0.0 + + + + Welcome to HTTPD + + -
-

HTTPD

-
Version 4.0.0 — MVS 3.8j
-
✓ Server is running
-

- HTTP/1.1 server for IBM MVS 3.8j on Hercules.
- Part of the mvslovers open-source ecosystem. -

-
- GitHub - mvsMF - mvslovers + +
+
HTTPD
+
+ +
+ +
+ ● SERVER ONLINE +
+ +

It works.
The mainframe is online.

+ +

+ You are connected to HTTPD, an HTTP/1.1 server running on MVS 3.8j. +

+ +
+ +
+ SYSTEM + MVS 3.8j
-
- HTTPD 4.0.0 — originally by Michael Dean Rayborn, maintained by Mike Großmann + +
+ SERVER + HTTPD
-
+ +
+ PROTOCOL + HTTP/1.1 +
+ +
+ +
+ + + From 71c4a43ba3ccf19461956571b6aeabcca86a9661 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 08:10:51 +0200 Subject: [PATCH 04/11] Update index.html --- static/index.html | 45 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/static/index.html b/static/index.html index 1e08b6e..4ae1aff 100644 --- a/static/index.html +++ b/static/index.html @@ -79,8 +79,24 @@ font-size: 0.75rem; } - a { + .links { + margin-top: 60px; + } + + .link { color: #8ab4ff; + text-decoration: none; + } + + .link:hover { + text-decoration: underline; + } + + .optional { + margin-top: 8px; + color: #777; + font-family: monospace; + font-size: 0.8rem; } footer { @@ -90,6 +106,15 @@ font-family: monospace; font-size: 0.8rem; } + + footer a { + color: #8ab4ff; + text-decoration: none; + } + + footer a:hover { + text-decoration: underline; + } @@ -130,12 +155,24 @@

It works.
The mainframe is online.

+
+ +
+ + Open mvsMF → + + +
+ Available if mvsMF is installed. +
+
+ +
+ From bf60f1b740953b33a39ea58d6b57808d762d7702 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 17:42:32 +0200 Subject: [PATCH 05/11] Gate the shipped /zosmf/* route, and say the display modules are going away Three corrections from a read-through against the live system. The shipped HTTPPRM0 left the /zosmf/* catch-all without an AUTH=, which is PUBLIC -- the whole mvsMF API, every dataset and job endpoint, to anyone who can reach the port. The running configuration on mvsdev has carried AUTH=TOKEN on that line all along; the pattern we ship did not. TOKEN is the right mode here rather than BASIC: it answers a bare 401 with no WWW-Authenticate, which is what an API client handles itself, and it keeps a browser from caching Basic credentials that outlive the token session. The commented-out display module lines had the same shape: uncommenting `# MOD=HTTPDM /.dm` produced a public arbitrary-storage reader. They now carry AUTH=BASIC, so uncommenting a line does what it looks like it does. docs/installation.md now says what the four non-server modules are for and where they are going. HTTPDSRV, HTTPDM, HTTPDMTT and ABEND0C1 are diagnostic, debugging and development tools -- they ship in 4.0.x so a problem on a live system can be looked at without a private build, and the next release will not deliver them. Nothing depends on them: HTTPD is the only module a started task names, and a server that never routed to the others cannot notice their absence. Step 3b told the reader to pre-allocate and then showed only the upload. It now shows the allocation too, with `zowe files create ps` and sizes derived from the artifacts (the load XMIT is ~650 KB, the sample library under 20 KB). The flag spellings were checked against the installed zowe rather than assumed. --- docs/installation.md | 46 +++++++++++++++++++++++++++++++++++++++----- samplib/httpprm0 | 20 ++++++++++++++----- 2 files changed, 56 insertions(+), 10 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 5e7240f..3ce6864 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -61,6 +61,18 @@ above are inert on a fresh install. That is deliberate: `/.dm` and `/.dmtt` hand out arbitrary storage and the console log, and `ABEND0C1` abends on purpose. See [step 7](#7-install-the-procedure-and-the-configuration). +> **The four are diagnostic, debugging and development tools, and they are on +> their way out.** They ship in 4.0.x so that a problem on a live system can be +> looked at without a private build — reading a control block beats guessing at +> one, and `/.dmtt` is often the fastest way to the console log. They are not +> production endpoints, and **the next release will not deliver them**: a server +> whose job is hosting an API has no business shipping an arbitrary-storage +> reader alongside it. Build them from source when you need them. +> +> Nothing depends on them. `HTTPD` is the only module the started task names, +> and removing the other four changes no behaviour of a server that never +> routed to them. + The sample library holds two members, `HTTPD` (the started task procedure) and `HTTPPRM0` (the configuration pattern). @@ -132,9 +144,14 @@ z/OSMF-compatible REST API, which is a separate product: ``` MOD=MVSMF /zosmf/info AUTH=NONE MOD=MVSMF /zosmf/services/authenticate AUTH=NONE -MOD=MVSMF /zosmf/* +MOD=MVSMF /zosmf/* AUTH=TOKEN ``` +The first two are public on purpose — the anonymous reachability probe and the +token login endpoint do their own auth, so the gate must not challenge them. +The catch-all behind them is where the datasets, jobs and files live, and it is +gated. First match wins, so the order matters. + If mvsMF is not installed, HTTPD starts and those routes register normally — the program is not looked for until a request first matches. The failure then shows up per request as @@ -224,8 +241,10 @@ enter them once in step 6. This guide uses `IBMUSER.HTTPD.LOAD.XMIT` and Whether you have to allocate them first depends on the upload path: **FTPD** and **IND$FILE** create the dataset from the attributes you supply, mvsMF and most other FTP servers need it to exist. Where a method says *pre-allocate*, -allocate both as `DSORG=PS, RECFM=FB, LRECL=80, BLKSIZE=3120`, primary ~50 -tracks, secondary 20 (TSO or ISPF 3.2). +allocate both as `DSORG=PS, RECFM=FB, LRECL=80, BLKSIZE=3120` — 50 tracks +primary for the load XMIT (roughly 650 KB), 5 for the sample library, secondary +about 10% of each. Method b) below shows this with zowe; TSO or ISPF 3.2 does +the same job. Pick **one** method: @@ -248,7 +267,17 @@ uploading through the thing you are about to stop. ### b) mvsMF (z/OSMF-compatible REST API), via zowe Only when a *different* server is up, or you are not replacing this one. It -requires the datasets to **exist first**, so *pre-allocate*, then: +requires the datasets to **exist first**, so allocate them, here with zowe +itself: + +``` +zowe files create ps "IBMUSER.HTTPD.LOAD.XMIT" \ + --recfm FB --lrecl 80 --blksize 3120 --size 50TRK +zowe files create ps "IBMUSER.HTTPD.SAMP.XMIT" \ + --recfm FB --lrecl 80 --blksize 3120 --size 5TRK +``` + +then upload: ``` zowe zos-files upload file-to-data-set httpd--load.xmit \ @@ -257,6 +286,11 @@ zowe zos-files upload file-to-data-set httpd--samplib.xmit \ "IBMUSER.HTTPD.SAMP.XMIT" --binary ``` +`--size` sets the primary allocation and gives you a secondary of about 10% of +it. The values above are for a 3390 and leave room to spare — the load XMIT is +roughly 650 KB, the sample library well under 20 KB. On a smaller device, or if +you hit an `SB37`, raise them. + ### c) Another FTP server (pre-allocate) *Pre-allocate* both datasets, then transfer **binary** into them — a plain @@ -494,7 +528,9 @@ LOC=/* AUTH=NONE static prefix, public on purpose The display modules deserve their own warning. `MOD=HTTPDM /.dm` with no `AUTH=` hands anyone who can reach the port arbitrary storage reads, and `/.dmtt` hands -them the console log. If you enable them, gate them: +them the console log. They are debugging tools that will not be shipped after +4.0.x (step 1) — enable them while you are diagnosing something, and gate them +whenever you do: ``` MOD=HTTPDSRV /.dsrv AUTH=FORM diff --git a/samplib/httpprm0 b/samplib/httpprm0 index 6c0b8ef..6c1cee7 100644 --- a/samplib/httpprm0 +++ b/samplib/httpprm0 @@ -84,13 +84,23 @@ # match wins): the anonymous reachability probe (/zosmf/info) and the token # login/logout endpoint (/zosmf/services/authenticate) do their own auth, so # the gate must not challenge them. +# TOKEN on the catch-all, not a blank: a route without AUTH= is PUBLIC, and +# leaving the whole API ungated would hand every dataset and job endpoint to +# anyone who can reach the port. TOKEN answers a bare 401 without a +# WWW-Authenticate, which is what an API client (Zowe, a SPA, curl scripts) +# wants -- see the AUTH= notes above. MOD=MVSMF /zosmf/info AUTH=NONE MOD=MVSMF /zosmf/services/authenticate AUTH=NONE -MOD=MVSMF /zosmf/* -# MOD=MVSMF /zosmf/* AUTH=TOKEN RES=FACILITY:MVSMF.ACCESS (protected API) -# MOD=HTTPDSRV /.dsrv AUTH=FORM (browser login) -# MOD=HTTPDM /.dm -# MOD=HTTPDMTT /.dmtt +MOD=MVSMF /zosmf/* AUTH=TOKEN +# Add a RACF/RAKF profile check on top of the login: +# MOD=MVSMF /zosmf/* AUTH=TOKEN RES=FACILITY:MVSMF.ACCESS +# +# The display modules read live storage and the console log, so none of them +# may be uncommented without an AUTH= of its own. They are development and +# diagnostic tools, not production endpoints. +# MOD=HTTPDSRV /.dsrv AUTH=FORM (browser login) +# MOD=HTTPDM /.dm AUTH=BASIC +# MOD=HTTPDMTT /.dmtt AUTH=BASIC # # ABEND0C1 allocates (?kb=n, default 128) and then abends S0C1 without freeing # -- the acceptance probe for the storage reclaim. Drive it a few hundred From 4b0274536f93fb08da4612447e4316754cfae7bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 20:21:24 +0200 Subject: [PATCH 06/11] Ship the document root as a UFS disk image, uploaded with IND$FILE static/index.html was in the repository and in no release artifact, so the package installed a server whose DOCROOT had nothing behind it. A UFS disk cannot travel the way the rest of the package does, and not for lack of tooling. SMP has no element type for a DSORG=PS/RECFM=U image and must never touch site content; TSO RECEIVE allocates its own target and refuses to merge into an existing dataset, which makes it a first-install-only transport for something an operator replaces. So the image ships as a plain file in the archive and goes up over IND$FILE, which needs nothing on the target beyond a 3270 session. make webroot builds dist/httpd-webroot.img from static/ with a pinned ufsd-utils (fetched into .mbt/tools/ when absent, because release CI runs the shared workflow and cannot install anything of its own). package and dist depend on it, and [distribution] extra puts it in the zip/tar.gz. samplib/httpwebr allocates HTTPD.@VRM@.WEBROOT.UFS -- SPACE=(4096,256), RECFM=U BLKSIZE=4096, primary extent only. installation.md 9 the operator's side: allocate, upload, mount, verify, and unmount before replacing. Measured rather than assumed: Blocking RECFM=U buffers to BLKSIZE through __fputc (libc370 @@fputc.c:24), so BLKSIZE(4096) writes whole 4096-byte blocks; the 1 MB image is 256 of them with no remainder. Options binary is IND$FILE's default and RECFM then defaults to U (ind_file370 indparse.c:249). Pre-allocate IND$FILE allocates an existing dataset DISP=SHR and takes its DCB (indmain.c:190, :273), so the documented upload needs no options and does not depend on which IND$FILE build a system carries. The trap that same DISP=SHR rewrites a dataset UFSD has mounted, so UNMOUNT is a numbered step rather than a footnote. Detection a BLKSIZE mismatch surfaces at MOUNT as UFSD062E (ufsd ufsd#sbl.c:69), not as a corrupt page. Encoding nothing to configure: http_send_file() translates UFS files with the hard-coded IBM-1047 table independent of CODEPAGE= (httpfile.c:70), which is what ufsd-utils writes. The round trip was measured byte for byte over the whole file and over all 256 values; only 0x85 and 0xF7 do not survive. The version in the dataset name settles what smp-todo called U6: a shipped image cannot land on a webroot the site built for itself. Fixes #252 --- Makefile | 71 +++++++++++++++ docs/installation.md | 207 ++++++++++++++++++++++++++++++++++++++++--- project.toml | 24 ++++- samplib/httpwebr | 35 ++++++++ smp-todo.md | 83 ++++++++++------- 5 files changed, 372 insertions(+), 48 deletions(-) create mode 100644 samplib/httpwebr diff --git a/Makefile b/Makefile index a25ecfe..a0f922b 100644 --- a/Makefile +++ b/Makefile @@ -1,2 +1,73 @@ MBT_ROOT := mbt include $(MBT_ROOT)/mk/mbt.mk + +# -- Webroot disk (issue #252) -------------------------------------- +# static/ ships as a formatted UFS370 image, because a UFS disk cannot +# travel any of the ways the rest of the package does: SMP has no element +# type for a DSORG=PS/RECFM=U image and must never touch site content, and +# TSO RECEIVE allocates its own target and refuses to merge into an +# existing dataset -- a first-install-only transport for something that +# gets updated. The operator uploads the image with IND$FILE instead; +# docs/installation.md carries the procedure. +# +# There is deliberately no codepage handling here. http_send_file() +# translates UFS files with the hard-coded IBM-1047 table, independent of +# the CODEPAGE= setting (src/httpfile.c), and IBM-1047 is what +# `ufsd-utils cp` writes -- measured byte for byte over the whole file, +# UTF-8 sequences included. Only 0x85 and 0xF7 fail to round-trip, so a +# text file must avoid characters whose UTF-8 encoding contains them. +# +# ufsd-utils is pinned rather than taken from PATH: `create` stamps an +# owner and a timestamp into the image, so the version that builds a +# release artifact is part of what is shipped. Release CI runs the shared +# mbt workflow and cannot install anything of its own, hence the fetch into +# .mbt/tools/. Pass UFSD_UTILS= to build against a different one. +# 1M is 256 blocks of 4096, which the inode list caps at 62 files -- the same +# 62 any disk up to 512 blocks gets, so a larger image buys space, not files. +# Owner and group are metadata: UFSD enforces the MOUNT's OWNER(), not the +# inode owner. They are named anyway, so a release artifact does not carry +# whatever userid happened to build it. +WEBROOT_IMG := $(DISTDIR)/httpd-webroot.img +WEBROOT_SRC := static +WEBROOT_SIZE := 1M +WEBROOT_OWNER := IBMUSER +WEBROOT_GROUP := SYSPROG + +UFSD_UTILS_VER := 1.0.1 +UFSD_UTILS_BIN := .mbt/tools/ufsd-utils-$(UFSD_UTILS_VER) +UFSD_UTILS ?= $(UFSD_UTILS_BIN) + +# Only the pinned binary is a prerequisite -- an overridden UFSD_UTILS names +# a program on PATH, which make would try (and fail) to build as a file. +WEBROOT_TOOL_DEP := $(if $(filter $(UFSD_UTILS_BIN),$(UFSD_UTILS)),$(UFSD_UTILS_BIN)) + +$(UFSD_UTILS_BIN): + $(E) "[webroot] fetching ufsd-utils $(UFSD_UTILS_VER)" + @mkdir -p $(dir $@) + @os=`uname -s | tr '[:upper:]' '[:lower:]'`; \ + arch=`uname -m`; \ + case "$$arch" in \ + x86_64|amd64) arch=amd64 ;; \ + arm64|aarch64) arch=arm64 ;; \ + *) echo "[webroot] no ufsd-utils release for $$arch" >&2; exit 1 ;; \ + esac; \ + name=ufsd-utils-$$os-$$arch; \ + curl -sSfL "https://github.com/mvslovers/ufsd-utils/releases/download/v$(UFSD_UTILS_VER)/$$name.tar.gz" \ + | tar xzOf - $$name > $@ || { rm -f $@; exit 1; } + @chmod +x $@ + +webroot: $(WEBROOT_IMG) + +$(WEBROOT_IMG): $(shell find $(WEBROOT_SRC) -type f) $(WEBROOT_TOOL_DEP) + $(E) "[webroot] $(notdir $@) ($(WEBROOT_SIZE), from $(WEBROOT_SRC)/)" + @mkdir -p $(DISTDIR) + @rm -f $@ + $(Q)$(UFSD_UTILS) create $@ --size $(WEBROOT_SIZE) --blksize 4096 \ + --owner $(WEBROOT_OWNER) --group $(WEBROOT_GROUP) > /dev/null + $(Q)$(UFSD_UTILS) cp -r $(WEBROOT_SRC)/ $@:/ + +# Both read it: 'package' ships it in the archive ([distribution] extra), +# and 'dist' re-renders that archive on its own. +package dist: webroot + +.PHONY: webroot diff --git a/docs/installation.md b/docs/installation.md index 3ce6864..5a89863 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -6,7 +6,7 @@ Hercules build) from the release distribution archive. The installation is managed by **SMP Release 4** — the SMP that ships with MVS 3.8j, not SMP/E. That means the system keeps a record of what was installed, and there is a supported way back out (see -[Removing HTTPD](#11-removing-httpd)). +[Removing HTTPD](#12-removing-httpd)). ## Getting help @@ -15,7 +15,7 @@ installed, and there is a supported way back out (see That is the only place bug reports are tracked. Please include the two build stamps HTTPD writes at startup (`HTTPD000I` and `HTTPD005I`, see -[step 9](#9-start-and-verify)) — they identify the exact build — plus the +[step 10](#10-start-and-verify)) — they identify the exact build — plus the console messages and, for an install problem, the job output. **Questions and general support** are on Discord: @@ -44,6 +44,7 @@ recognise which file is which. | `httpd--samplib.xmit` | the sample library: STC procedure and configuration pattern | | `httpd--alloc.jcl` | allocates the datasets SMP installs into — **run once** | | `httpd--inst.jcl` | receives everything and installs it — repeatable | +| `httpd-webroot.img` | the document root as a UFS370 disk image — outside SMP, see [step 9](#9-the-webroot-disk) | The load library holds five modules: @@ -73,8 +74,9 @@ See [step 7](#7-install-the-procedure-and-the-configuration). > and removing the other four changes no behaviour of a server that never > routed to them. -The sample library holds two members, `HTTPD` (the started task procedure) and -`HTTPPRM0` (the configuration pattern). +The sample library holds three members: `HTTPD` (the started task procedure), +`HTTPPRM0` (the configuration pattern) and `HTTPWEBR` (a job that allocates the +dataset the webroot image is uploaded to). Where everything ends up: @@ -82,8 +84,12 @@ Where everything ends up: HTTPD..LINKLIB the load modules -- point STEPLIB here HTTPD..SAMPLIB the patterns you copy from in step 7 HTTPD..AHTTPLOD SMP's distribution library, the base a RESTORE returns to +HTTPD..WEBROOT.UFS the document root, if you upload the shipped one (step 9) ``` +The last one is not SMP's: it is a filesystem image, and it holds site content +that an `APPLY` must never touch. Step 9 is where it comes from. + --- ## 2. Prerequisites @@ -94,7 +100,8 @@ HTTPD..AHTTPLOD SMP's distribution library, the base a RESTORE returns t - **RAKF** — see [Authorisation](#authorisation) below. HTTPD does not start without either RAKF or an APF list entry, and no configuration option turns that off. -- **UFSD**, only if you want to serve static files — see below. +- **UFSD**, only if you want to serve static files — see below. The archive + ships a document root for it as a disk image (step 9). - **mvsMF**, only if you want the REST API the shipped configuration routes to — see below. - A userid authorised to submit jobs, to update a PROCLIB in the started-task @@ -129,6 +136,10 @@ the start. On a deployment that will never have UFSD, `UFS=0` in the configuration member skips the initialisation altogether and the warning with it. +With UFSD there, the archive has a document root ready for it — +`httpd-webroot.img`, a formatted filesystem holding the welcome page, which +[step 9](#9-the-webroot-disk) uploads and mounts. + Install HTTPD now and add UFSD later if you want it: , with its own guide at [ufsd/docs/installation.md](https://github.com/mvslovers/ufsd/blob/main/docs/installation.md). @@ -246,6 +257,11 @@ primary for the load XMIT (roughly 650 KB), 5 for the sample library, secondary about 10% of each. Method b) below shows this with zowe; TSO or ISPF 3.2 does the same job. +The third file that has to reach the host, `httpd-webroot.img`, is **not** one of +these: it is a filesystem image with its own record format, it is not received +by anything, and it is only needed once the server runs. It has its own step — +[step 9](#9-the-webroot-disk) — and nothing here applies to it. + Pick **one** method: ### a) FTP — mvslovers/ftpd (no pre-allocation) @@ -303,6 +319,8 @@ them unnecessary. No pre-allocation needed. Use your emulator's file transfer in **binary** mode (no ASCII/CRLF translation) with `RECFM=FB LRECL=80 BLKSIZE=3120`. The exact option syntax is client-dependent — consult its file-transfer documentation. +[Step 9](#9-the-webroot-disk) walks an IND$FILE upload through in full, for the +webroot image; the same emulator handling applies here. --- @@ -323,7 +341,7 @@ Expect `COND CODE 0000`. > install, `HTTPD..AHTTPLOD` holds SMP's accepted copy of the modules; a > re-run that scratched it would leave the SMP inventory reporting an install > that is no longer on the system, and nothing would say so. To start over, -> reject the SYSMOD first — see [Removing HTTPD](#11-removing-httpd). +> reject the SYSMOD first — see [Removing HTTPD](#12-removing-httpd). --- @@ -332,7 +350,7 @@ Expect `COND CODE 0000`. Only relevant when you are upgrading. The APPLY writes into `HTTPD..LINKLIB`, and each release has its own — so a running *older* HTTPD does not block the install. It does, however, keep running the old modules until -you restart it (step 9) against the procedure you copy in step 7. +you restart it (step 10) against the procedure you copy in step 7. ``` /P HTTPD @@ -419,6 +437,9 @@ Copy from `HTTPD..SAMPLIB`: `SYS2.PROCLIB` is the usual home for the procedure. +The third member, `HTTPWEBR`, is not copied anywhere: it is a job you submit +straight from the sample library when you get to [step 9](#9-the-webroot-disk). + ### Which PARMLIB The shipped procedure defaults to `D='SYS2.PARMLIB'`. **On TK5 that dataset @@ -576,7 +597,166 @@ client can log in. --- -## 9. Start and verify +## 9. The webroot disk + +`DOCROOT` names a path in the UFSD filesystem, so the pages HTTPD serves live on +a UFS disk and not in a library. The archive carries one ready to use: +`httpd-webroot.img`, a 1 MB UFS370 filesystem holding the welcome page. Three +steps put it on the system — allocate, upload, mount — and none of them belongs +to SMP. + +**Why it travels on its own.** SMP has no element type for a `DSORG=PS`, +`RECFM=U` image, and site content is precisely what an `APPLY` must never +touch. TSO RECEIVE is no better: it allocates its own target and refuses to +merge into an existing dataset, which makes it a first-install-only transport +for something you will replace. So the disk ships as a plain file and goes up +over **IND$FILE**, which needs nothing on the target beyond a 3270 session. + +This step needs **UFSD** (step 2). Without it there is nothing to mount and +nothing static to serve; every `MOD=` route works regardless. + +**Already have a webroot?** Then read this for the mechanics and keep your own +disk. Nothing here can overwrite it — the dataset is named for this release. + +### a) Allocate the dataset + +`HTTPD..SAMPLIB(HTTPWEBR)` does exactly this and nothing else: + +```jcl +//ALLOC EXEC PGM=IEFBR14 +//WEBROOT DD DSN=HTTPD..WEBROOT.UFS,DISP=(NEW,CATLG), +// UNIT=SYSDA,SPACE=(4096,256), +// DCB=(DSORG=PS,RECFM=U,BLKSIZE=4096) +``` + +**Run it before the upload, not after.** IND$FILE allocates an *existing* +dataset `DISP=SHR` and takes the DCB from its label; only when the dataset is +missing does it invent one of its own. Allocating it here is what pins +`BLKSIZE=4096` — the block size the image was formatted with, and the one thing +about the transfer that has to be right. + +`SPACE` is counted in blocks of 4096, so 256 blocks is the megabyte the image +occupies. **Primary extent only**: the filesystem is addressed by block number +within the primary extent, so anything in a secondary would never be reached. + +### b) Upload it with IND$FILE + +The image must arrive byte for byte: **binary**, no ASCII translation, no CRLF +conversion. With the dataset allocated, the command carries no options at all — +which also makes it independent of which IND$FILE build your system has: + +``` +IND$FILE PUT HTTPD.V4R0M0.WEBROOT.UFS +``` + +Binary is IND$FILE's default; `ASCII` and `CRLF` are what you would have to add +to break it. + +Most emulators issue that command for you. x3270, c3270 and wc3270 take it as +one action, and their file-transfer dialog asks for the same fields: + +``` +Transfer(Direction=send, + LocalFile=httpd-webroot.img, + HostFile=HTTPD.V4R0M0.WEBROOT.UFS, + Host=tso, Mode=binary, Exist=replace) +``` + +Leave `Recfm`, `Lrecl`, `Blksize` and the space fields **unset**: the dataset +exists, so its label decides, and an emulator's allocation defaults are not +worth auditing. Position the session on a cleared TSO **READY** screen (ISPF +option 6 also works) before starting the transfer. + +If you would rather let IND$FILE create the dataset, it needs to be told +everything the allocation job otherwise says: + +``` +IND$FILE PUT HTTPD.V4R0M0.WEBROOT.UFS (RECFM(U) BLKSIZE(4096) TRACKS SPACE(70) +``` + +70 tracks holds a megabyte even on a 3350, where a 4096-byte block packs four to +a track; a 3380 or 3390 needs half that. There is no secondary quantity on +purpose (see above). + +A megabyte over a 3270 session takes minutes rather than seconds. That is the +transfer, not a hang. + +### c) Mount it + +The mount belongs to **UFSD**, not to HTTPD. In its Parmlib member: + +``` +MOUNT DSN(HTTPD.V4R0M0.WEBROOT.UFS) PATH(/www) MODE(RO) +``` + +or, without a restart — note that the operator command spells its operands with +`=` and commas where the Parmlib statement uses parentheses: + +``` +/F UFSD,MOUNT DSN=HTTPD.V4R0M0.WEBROOT.UFS,PATH=/www,MODE=RO +``` + +`/www` is HTTPD's default `DOCROOT`; if you changed it in `HTTPPRM0`, mount it +there instead. `MODE(RO)` is the default and the right setting here — the +shipped disk is product content and nothing in the server writes to it. + +**UFSD first, then HTTPD.** The filesystem has to be up and mounted before the +server that serves from it — a runtime dependency SMP cannot express, which is +why the SYSMOD declares no prerequisite on UFSD at all. + +### d) Verify + +``` +/F UFSD,MOUNT LIST +curl -v http://your-mvs-host:8080/ +``` + +`/` serves `/www/index.html`: HTTPD appends `index.html` to a request for a +directory. + +| What you see | What it means | +|---|---| +| `UFSD062E SUPERBLOCK VALIDATION FAILED FOR …` | the dataset's `BLKSIZE` is not the image's 4096 — or the transfer was not binary | +| `HTTPD044W UNABLE TO INITIALIZE FILE SYSTEM` | UFSD is not running (step 2) | +| `404` on `/` | mounted somewhere other than `DOCROOT` | +| a page of mojibake | the transfer translated the bytes; upload again in binary | + +### Replacing the content later + +**Unmount before you re-upload.** IND$FILE allocates `DISP=SHR`, so it will +happily rewrite a dataset UFSD has open — under the server's own buffers: + +``` +/F UFSD,UNMOUNT PATH=/www + ... upload ... +/F UFSD,MOUNT DSN=HTTPD.V4R0M0.WEBROOT.UFS,PATH=/www,MODE=RO +``` + +For pages of your own, build the image on your workstation with +[ufsd-utils](https://github.com/mvslovers/ufsd-utils) and upload it the same way: + +``` +ufsd-utils create mysite.img --size 1M --blksize 4096 --owner IBMUSER +ufsd-utils cp -r ./mysite/ mysite.img:/ +``` + +Text files are stored in **IBM-1047**, which is what `ufsd-utils` writes by +default and what HTTPD's static file path translates back with — a UFS file is +converted with that table regardless of the `CODEPAGE=` setting, which governs +MVS datasets and the server's own output. So there is nothing to configure here, +and nothing to match up. + +With mvsMF installed there is a second route for single files — +`PUT /zosmf/restfiles/fs/www/index.html` — but only into a filesystem mounted +`MODE(RW)`, which the shipped disk is not. + +One thing the image is not: reproducible. It carries its own creation +timestamp, so two builds of the same commit differ byte for byte. Compare it +against the archive you downloaded, never against one you rebuilt. + +--- + +## 10. Start and verify ``` /S HTTPD default member (HTTPPRM0) @@ -653,7 +833,7 @@ and `DISPLAY TIme` need one and two letters respectively. --- -## 10. What HTTPD serves +## 11. What HTTPD serves Two kinds of route, both declared in the configuration member, both carrying the same per-route auth policy: @@ -679,7 +859,7 @@ writing your own module is --- -## 11. Removing HTTPD +## 12. Removing HTTPD Because the installation is SMP-managed, there is a defined way back — but it is **not** the `RESTORE` followed by `REJECT` that SMP documentation leads you to @@ -779,8 +959,9 @@ Leave `HTTPD..SAMPLIB` alone if you like — the install job's `DELOLD` ste scratches it on its own. **5. What is not removed, because SMP never owned it:** the procedure and the -configuration member you copied in step 7, and your RAKF definitions. Those are -yours to delete. +configuration member you copied in step 7, your RAKF definitions, and the +webroot disk `HTTPD..WEBROOT.UFS` with the `MOUNT` statement that names it. +Those are yours to delete — unmount the disk before you scratch it. > The `RESTORE`/`REJECT` behaviour above was measured on 2026-08-14 against an > accepted FMID from a package built by this same generator, on an MVS/CE system @@ -813,6 +994,8 @@ yours to delete. | A route answers `200` to anyone | It carries no `AUTH=`, or no route claims the path at all. Both are public by design — step 7. `/.dsrv?target=MOD` prints the policy each route actually got | | `401` on a route showing `AUTH=NONE` | Not HTTPD's gate. mvsMF runs its own auth track on `/zosmf/*` — establish which layer answered before debugging HTTPD's | | `S106` at start on a freshly installed library | The XMIT was uploaded in text mode. Re-upload in **binary** and re-run the install job | +| `UFSD062E SUPERBLOCK VALIDATION FAILED` at `MOUNT` | The webroot dataset was not allocated `RECFM=U BLKSIZE=4096`, or the image was uploaded in text mode — step 9 | +| `404` on `/` with UFSD running | The webroot is mounted somewhere other than `DOCROOT`, or nothing is mounted there at all — step 9 | | The step ends `CC 0000` but nothing was ever served | A clean `/P HTTPD` and a refused start are `CC 0000` and `CC 0008`. If it is 0000, the server ran — look for what stopped it | For the complete message reference, see diff --git a/project.toml b/project.toml index ad75ee0..3dc849c 100644 --- a/project.toml +++ b/project.toml @@ -283,11 +283,21 @@ headers = [ ] # -- Distribution (SMP4 install package) -------------------------- -# Turns `make package` into an installable product, the same two transports -# ufsd and ftpd ship with: +# Turns `make package` into an installable product, on the two transports ufsd +# and ftpd ship with, plus a third one they have no need for: # # load modules -> XMIT -> staging HTTPLOAD -> SMP ++MOD -> HTTPD..LINKLIB # samplib/ -> XMIT -> TSO RECEIVE -> HTTPD..SAMPLIB +# static/ -> UFS370 image -> IND$FILE -> HTTPD..WEBROOT.UFS +# +# The webroot disk (issue #252) rides neither of the first two, and not because +# of a gap in the tooling: SMP has no element type for a DSORG=PS/RECFM=U image +# and must never touch site content, and TSO RECEIVE allocates its own target +# and refuses to merge into an existing one -- a first-install-only transport +# for something an operator updates. So it travels as a plain file in the +# archive (`extra` below) and goes up over IND$FILE, which needs nothing on the +# target beyond a 3270 session. `make webroot` builds it; the Makefile carries +# the why, docs/installation.md the operator's side. # # SMP *copies* the host-bound modules rather than re-binding them (a COPY-style # ++JCLIN is what says so), which is what keeps HTTPD's ac = 1 and every custom @@ -327,6 +337,16 @@ headers = [ # package tells the operator to read a file it does not contain. readme = "docs/installation.md" +# The webroot disk, put in the archive as `httpd-webroot.img` -- `extra` takes +# the basename, so the path here is where `make webroot` writes it and the name +# an operator sees is the file's own. Listed rather than generated by mbtdist: +# the image is not a dataset the install job creates, and nothing in the SYSMOD +# or the RECEIVE plan knows about it. `make package` and `make dist` both +# depend on the target that builds it, because a missing `extra` file is a hard +# error here -- deliberately: an archive quietly missing the webroot would look +# complete and serve nothing on /. +extra = ["dist/httpd-webroot.img"] + [distribution.smp] # One FMID per minor release, spent exactly once: it names a functional level, # and a changed one is a new level. Patches on top of it ship as PTFs. 4.0.x diff --git a/samplib/httpwebr b/samplib/httpwebr new file mode 100644 index 0000000..5a32130 --- /dev/null +++ b/samplib/httpwebr @@ -0,0 +1,35 @@ +//HTTPWEBR JOB (ACCT),'ALLOC HTTPD WEBROOT',CLASS=A,MSGCLASS=H, +// MSGLEVEL=(1,1),NOTIFY=&SYSUID +//* +//* HTTPWEBR - allocate the dataset the webroot disk is uploaded to +//* +//* The release archive carries httpd-webroot.img: a formatted UFS370 +//* filesystem holding the pages HTTPD serves from DOCROOT. You upload +//* it with IND$FILE and mount it with UFSD. The installation guide +//* has the whole procedure -- this job is only its first step. +//* +//* RUN THIS BEFORE THE UPLOAD. IND$FILE allocates an existing dataset +//* DISP=SHR and takes the DCB from its label; it invents one only when +//* the dataset is not there. Allocating it here is what pins +//* BLKSIZE=4096, the block size the image was formatted with. UFSD +//* compares the two at MOUNT and refuses a mismatch with: +//* +//* UFSD062E SUPERBLOCK VALIDATION FAILED FOR +//* +//* Primary extent only, on purpose. The filesystem is addressed by +//* block number within the primary extent, so blocks in a secondary +//* would never be reached. SPACE is counted in blocks of 4096 here, +//* which makes 256 blocks the 1 MB the shipped image occupies. MVS +//* rounds the request up to a track boundary; the few blocks that adds +//* sit past the end of the filesystem, because the superblock -- not +//* the dataset -- is what says how large the filesystem is. +//* +//* Change the dataset name, UNIT and VOLUME to suit. The name below +//* is the one the installation guide uses. An image larger than the +//* shipped one needs a matching SPACE: count it in 4096-byte blocks. +//* +//ALLOC EXEC PGM=IEFBR14 +//WEBROOT DD DSN=HTTPD.@VRM@.WEBROOT.UFS,DISP=(NEW,CATLG), +// UNIT=SYSDA,SPACE=(4096,256), +// DCB=(DSORG=PS,RECFM=U,BLKSIZE=4096) +// diff --git a/smp-todo.md b/smp-todo.md index 638d485..a28d2de 100644 --- a/smp-todo.md +++ b/smp-todo.md @@ -9,7 +9,7 @@ die Messungen vermerkt. Was ein Betreiber tun muss, steht in Dieses Dokument hält nur noch das, was **für httpd offen** ist. -> *Stand: 2026-08-23, gegen `[distribution]` in `project.toml` abgeglichen.* +> *Stand: 2026-08-24, gegen `[distribution]` in `project.toml` abgeglichen.* > **Die frühere Fassung verwies auf `../SMP-COOKBOOK.md` und > `../SMP-INSTALLATION.md`. Beide Dateien gibt es nicht mehr.** Der Spike liegt @@ -50,7 +50,7 @@ haben diesen Job vor ihrem Tag gefahren, httpd noch nicht — der Kommentar in Die Generalprobe aus einem `-dev`-Baum. Ein Testlauf unter `THTP400`, der abbricht oder halb angewendet wird, belegt genau die ID, die das getaggte 4.0.0 braucht — und das CDS lässt sich hinterher nur mit `UCLIN` bereinigen -(`docs/installation.md` §11). +(`docs/installation.md` §12). Mit mbt ist das eine Zeile: `fmid` in `project.toml` auf `TTST400` setzen, `make package`, installieren — **und die Änderung nie committen**. @@ -60,40 +60,55 @@ man etwas dafür tun muss: `@VRM@` kommt aus der Projektversion, und `4.0.0-dev` ergibt `V4R0M0D`, das getaggte `4.0.0` dagegen `V4R0M0`. Der Test lebt also in `HTTPD.V4R0M0D.*`, das Release in `HTTPD.V4R0M0.*`. -Aufräumen danach: UCLIN-Job aus `docs/installation.md` §11 mit `TTST400`, dann +Aufräumen danach: UCLIN-Job aus `docs/installation.md` §12 mit `TTST400`, dann die Datasets löschen, dann `LIST CDS/ACDS SYSMOD(THTP400)` — das ist zugleich O1. -### O3 — UFS-Webroot: SMP kann das nicht ausliefern - -Eine UFS-Disk ist ein `DSORG=PS`, `RECFM=U`, `BLKSIZE=4096`-Binärimage; SMP4 -kennt dafür keinen Elementtyp (es kennt nur -`++MOD/MAC/SRC/MACUPD/SRCUPD/ZAP`). Sie ist außerdem **Site-Inhalt** — ein -erneutes APPLY dürfte sie nie anfassen. - -Heute steht in `docs/installation.md`, dass ohne UFSD nur die `MOD=`-Routen -laufen und `HTTPD044W` kommt. Das ist ehrlich, aber es ist keine Auslieferung. -Offen: - -- [ ] **U1** Image bauen — `ufsd-utils create webroot.img --size 10M`, - `ufsd-utils cp -r static/ webroot.img:/`, danach `ufsd-utils ls -l` - gegenprüfen (Falle T3) -- [ ] **U2** Hochladen: `ufsd-utils upload webroot.img --dsn HTTPD.WEBROOT` -- [ ] **U3** Mount dokumentieren — `UFSDPRMx` gehört **ufsd**, nicht httpd: - `MOUNT DSN(HTTPD.WEBROOT) PATH(/www) MODE(RO)`, oder dynamisch - `/F UFSD,MOUNT DSN=HTTPD.WEBROOT,PATH=/www,MODE=RO`. Kein `++MACUPD` in - ufsds Parmlib -- [ ] **U4** Reihenfolge: **ufsd zuerst**, Dateisystem gemountet, `/www` - existiert — *dann* httpd. Eine Laufzeitabhängigkeit, die SMP nicht - abbilden kann -- [ ] **U5** `make webroot` + CI-Asset `httpd--webroot.img`, mit - SHA256 statt eines Reproduzierbarkeitsversprechens -- [ ] **U6** **Update-Verhalten festlegen** — `.SAMPLE`-Name oder Existenzprüfung. - Ein `ufsd-utils upload --replace` im Update-Job wäre Datenverlust beim - Betreiber - -`[distribution] extra = [...]` kann eine Datei ins Archiv legen, ohne SMP zu -behelligen — das ist der wahrscheinliche Weg für U5, sobald U6 entschieden ist. +### O3 — UFS-Webroot: entschieden und umgesetzt (Issue #252) + +Die Disk fährt **nicht** über SMP und **nicht** über XMIT, sondern als Datei im +Archiv und per **IND$FILE** aufs Ziel. Beides aus einem strukturellen Grund, +nicht aus Werkzeugmangel: + +- SMP4 kennt für ein `DSORG=PS`/`RECFM=U`-Image keinen Elementtyp + (`++MOD/MAC/SRC/MACUPD/SRCUPD/ZAP` ist die ganze Liste), und es ist + **Site-Inhalt** — ein APPLY dürfte es nie anfassen. +- TSO RECEIVE legt sein Ziel selbst an und weigert sich, in ein bestehendes + Dataset zu mischen: ein Transport nur für die Erstinstallation, für etwas, das + der Betreiber ersetzt. (`xmit370` könnte das Format ohnehin nicht — Verzeichnis + → PDS, `--recfm fb|f`, LRECL 80.) + +Umgesetzt: + +- **`make webroot`** baut `dist/httpd-webroot.img` aus `static/` mit einem + gepinnten `ufsd-utils` (1 MB = 256 Blöcke, `--owner`/`--group` gesetzt, damit + im Artefakt keine Build-Maschinen-Userid steht). `package` und `dist` hängen + davon ab, `[distribution] extra` legt es ins Archiv. +- **`samplib/httpwebr`** allokiert `HTTPD.@VRM@.WEBROOT.UFS` + (`SPACE=(4096,256)`, `RECFM=U BLKSIZE=4096`, nur Primärextent). +- **`docs/installation.md` §9** ist der Betreiberweg: allokieren, IND$FILE, + mounten, prüfen, ersetzen. + +Was dabei gemessen wurde und in der Doku steht: + +| Frage | Befund | +|---|---| +| Blockung | RECFM=U puffert über `__fputc` bis BLKSIZE (libc370 `@@fputc.c:24`) → `BLKSIZE(4096)` schreibt exakte 4096er-Blöcke; 1 MB = 256 ganze Blöcke | +| Optionen | Binär ist Default, RECFM dann `U` (ind_file370 `indparse.c:249`) | +| Vorher allokieren | IND$FILE nimmt ein existierendes Dataset DISP=SHR mitsamt DCB (`indmain.c:190`, `:273`) → Upload ohne jede Option, unabhängig vom IND$FILE-Build | +| Falle | dasselbe DISP=SHR schreibt auch in ein *gemountetes* Dataset → `UNMOUNT PATH=/www` ist ein nummerierter Schritt | +| Fehlerbild | BLKSIZE-Mismatch fällt beim MOUNT auf: `UFSD062E` (ufsd `ufsd#sbl.c:69`) | +| Codepage | keine Entscheidung nötig: `http_send_file()` übersetzt UFS-Dateien fest mit IBM-1047 (`src/httpfile.c:70`), unabhängig von `CODEPAGE=` — genau was `ufsd-utils cp` schreibt. Round-Trip byteweise gemessen, inkl. UTF-8; nur `0x85` und `0xF7` überleben ihn nicht | + +Damit ist auch **U6** (Datenverlust beim Update) erledigt, ohne +`.SAMPLE`-Konstruktion: das Dataset trägt die Version im Namen, kann also die +Platte des Betreibers gar nicht treffen. + +Offen geblieben: + +- [ ] **U5-Rest** SHA256 der Release-Assets — mbt veröffentlicht heute keine + Prüfsummen. Das Image trägt einen Erstellungszeitstempel, ist also nicht + reproduzierbar; die Doku sagt das auch so, statt es zu versprechen. ### O4 — Setup-Job: ausliefern oder Handarbeit lassen? @@ -153,7 +168,7 @@ abgearbeitet oder ersetzt: zurückzunehmen. Der Preis ist, dass die FMID selbst permanent wird: `RESTORE` scheitert, weil akzeptiert, und `REJECT`, weil der ACCEPT die MCS aus dem SMPPTS entfernt. Der Weg zurück ist `UCLIN`, beschrieben in - `docs/installation.md` §11. **Service (PTFs) wird weiterhin nie akzeptiert.** + `docs/installation.md` §12. **Service (PTFs) wird weiterhin nie akzeptiert.** --- From 4032125425d571a772adaca5bbe7a581ecf18ccd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 20:22:45 +0200 Subject: [PATCH 07/11] TODO: reconcile after #252, and name what actually blocks the 4.0.0 tag The ranking said nothing open blocks 4.0.0, which was true and unhelpful: the release work is in smp-todo.md (the FMID check and the dry run), not in the tracker at all. Say so, and record that O3 closed with #252. --- TODO.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/TODO.md b/TODO.md index de659e6..fbcad28 100644 --- a/TODO.md +++ b/TODO.md @@ -11,9 +11,9 @@ stops. `CLAUDE.md` forbids a task list in itself because a copy of a tracker is wrong the first time someone closes something, and the only defence that works is to hold nothing worth going stale. -*Last reconciled against the tracker: 2026-08-23, three issues open (#250 filed -that day; #237 closed by PR #249, and before it #245 by PR #248, #233 by -PR #244, #242 by PR #246 and #243 by PR #247).* +*Last reconciled against the tracker: 2026-08-24, three issues open (#252 filed +and closed the same day by PR #253; before it #250, #237 by PR #249, #245 by +PR #248, #233 by PR #244, #242 by PR #246 and #243 by PR #247).* --- @@ -39,6 +39,12 @@ exit that could end a refused start `CC 0000`; nothing in that thread is open, and `docs/messages.md` §*A refused start* is where the resulting contract is written down. +**What is left before the 4.0.0 tag is not in the tracker at all** — it is the +install package, and [`smp-todo.md`](smp-todo.md) holds it: the `THTP400` check +against CDS and ACDS on both stands (O1), and the dry run under the throwaway +FMID (O2). O3 closed with #252, which put the document root in the archive as a +UFS image; what remains of it is a checksum for the release assets. + --- ### 1 · #250 — does a LINKed module survive in the Job Pack Area? From cfe697ab27b3f07b9d16e1ae84fc1480ea3b8481 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 20:27:51 +0200 Subject: [PATCH 08/11] Rebuild the webroot image when a file leaves static/, not only when one changes The prerequisite list was files only. Adding one is covered -- make expands the wildcard when it parses the Makefile, so the new file is in the list and is newer than the image -- but deleting one is not: the image stays newer than everything still there, and the archive would go on shipping the file that was removed. A directory's mtime moves when an entry is added or removed, so the directories join the file list. Measured both ways with the image backdated so the comparison is not decided by whole-second timestamps: adding rebuilds, deleting rebuilds and drops the file from the image, an unchanged tree does nothing. Also two notes rather than behaviour: why the webroot dataset is the one name with a fourth qualifier, and that the emulator types IND$FILE into whatever field the cursor is on -- it does not find a command line for you. --- Makefile | 7 ++++++- docs/installation.md | 8 ++++++-- project.toml | 6 +++++- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index a0f922b..6096b14 100644 --- a/Makefile +++ b/Makefile @@ -58,7 +58,12 @@ $(UFSD_UTILS_BIN): webroot: $(WEBROOT_IMG) -$(WEBROOT_IMG): $(shell find $(WEBROOT_SRC) -type f) $(WEBROOT_TOOL_DEP) +# The directories are prerequisites next to the files: a *new* file is picked +# up either way, because make expands the wildcard when it parses this and the +# file is then newer than the image -- but a *deleted* one leaves an image that +# is newer than everything still there, and it would go on shipping the file. +# A directory's mtime moves when an entry is added or removed, which covers it. +$(WEBROOT_IMG): $(shell find $(WEBROOT_SRC) -type f -o -type d) $(WEBROOT_TOOL_DEP) $(E) "[webroot] $(notdir $@) ($(WEBROOT_SIZE), from $(WEBROOT_SRC)/)" @mkdir -p $(DISTDIR) @rm -f $@ diff --git a/docs/installation.md b/docs/installation.md index 5a89863..0aa971a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -664,8 +664,12 @@ Transfer(Direction=send, Leave `Recfm`, `Lrecl`, `Blksize` and the space fields **unset**: the dataset exists, so its label decides, and an emulator's allocation defaults are not -worth auditing. Position the session on a cleared TSO **READY** screen (ISPF -option 6 also works) before starting the transfer. +worth auditing. + +Either way the session has to sit on an input field that can accept the command +before the transfer starts — a cleared TSO **READY** screen, or ISPF option 6. +The emulator types `IND$FILE` into whatever field the cursor is on; it does not +find one for you. If you would rather let IND$FILE create the dataset, it needs to be told everything the allocation job otherwise says: diff --git a/project.toml b/project.toml index 3dc849c..dfe7783 100644 --- a/project.toml +++ b/project.toml @@ -318,7 +318,11 @@ headers = [ # # Every value is a dataset name; the ddname SMP addresses it by is always the # last qualifier, so LINKLIB, SAMPLIB, HTTPLOAD and AHTTPLOD fall out of the -# names. @VRM@ becomes V4R0M0 at package time (V4R0M0D while the version still +# names. The webroot is the one name with a fourth qualifier +# (HTTPD.@VRM@.WEBROOT.UFS) and it is deliberate: no ddname is derived from it +# because nothing here allocates or receives it, and .UFS says at a glance that +# the dataset is a filesystem image rather than a library. Do not normalise it +# into the three-qualifier pattern -- it is not part of that scheme. @VRM@ becomes V4R0M0 at package time (V4R0M0D while the version still # carries -dev). ufsd/ftpd spell these LOAD / ALOD, which for # a five-letter product would be nine characters; HTTPLOAD/AHTTPLOD keeps the # suffix and drops the letter, rather than keeping HTTPD and truncating the From 8051007f77fb29a0692632d670f84ea8c90a7676 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 20:55:21 +0200 Subject: [PATCH 09/11] Build the webroot image under build/, not dist/ dist/ is not a scratch directory: the release workflow publishes every file in it as a GitHub Release asset (`gh release create ... dist/*`). An image built there therefore shipped twice -- once inside the archive, where it belongs beside the README and the jobs, and once on its own as `httpd-webroot.img`, a name with no version in it sitting between httpd--load.xmit and httpd--dist.zip. Nothing else moves: `extra` takes the basename, so the file inside the archive is called what it was called before, and the installation guide is unchanged. --- Makefile | 11 +++++++++-- project.toml | 21 +++++++++++++-------- smp-todo.md | 2 +- 3 files changed, 23 insertions(+), 11 deletions(-) diff --git a/Makefile b/Makefile index 6096b14..a2b152b 100644 --- a/Makefile +++ b/Makefile @@ -27,7 +27,14 @@ include $(MBT_ROOT)/mk/mbt.mk # Owner and group are metadata: UFSD enforces the MOUNT's OWNER(), not the # inode owner. They are named anyway, so a release artifact does not carry # whatever userid happened to build it. -WEBROOT_IMG := $(DISTDIR)/httpd-webroot.img +# +# It is built under $(BUILDDIR) and NOT under $(DISTDIR), which is not a +# detail: the release workflow publishes `dist/*` as GitHub Release assets, so +# an image sitting there would appear beside the versioned artifacts under a +# name carrying no version at all -- and as a second copy of what the archive +# already holds. The archive is where it belongs, next to the README and the +# jobs an operator needs with it. +WEBROOT_IMG := $(BUILDDIR)/webroot/httpd-webroot.img WEBROOT_SRC := static WEBROOT_SIZE := 1M WEBROOT_OWNER := IBMUSER @@ -65,7 +72,7 @@ webroot: $(WEBROOT_IMG) # A directory's mtime moves when an entry is added or removed, which covers it. $(WEBROOT_IMG): $(shell find $(WEBROOT_SRC) -type f -o -type d) $(WEBROOT_TOOL_DEP) $(E) "[webroot] $(notdir $@) ($(WEBROOT_SIZE), from $(WEBROOT_SRC)/)" - @mkdir -p $(DISTDIR) + @mkdir -p $(dir $@) @rm -f $@ $(Q)$(UFSD_UTILS) create $@ --size $(WEBROOT_SIZE) --blksize 4096 \ --owner $(WEBROOT_OWNER) --group $(WEBROOT_GROUP) > /dev/null diff --git a/project.toml b/project.toml index dfe7783..f86692b 100644 --- a/project.toml +++ b/project.toml @@ -342,14 +342,19 @@ headers = [ readme = "docs/installation.md" # The webroot disk, put in the archive as `httpd-webroot.img` -- `extra` takes -# the basename, so the path here is where `make webroot` writes it and the name -# an operator sees is the file's own. Listed rather than generated by mbtdist: -# the image is not a dataset the install job creates, and nothing in the SYSMOD -# or the RECEIVE plan knows about it. `make package` and `make dist` both -# depend on the target that builds it, because a missing `extra` file is a hard -# error here -- deliberately: an archive quietly missing the webroot would look -# complete and serve nothing on /. -extra = ["dist/httpd-webroot.img"] +# the basename, so the path here is only where `make webroot` writes it and the +# name an operator sees is the file's own. Listed rather than generated by +# mbtdist: the image is not a dataset the install job creates, and nothing in +# the SYSMOD or the RECEIVE plan knows about it. `make package` and `make dist` +# both depend on the target that builds it, because a missing `extra` file is a +# hard error here -- deliberately: an archive quietly missing the webroot would +# look complete and serve nothing on /. +# +# Under build/ rather than dist/ on purpose. The release workflow publishes +# `dist/*` as Release assets, so an image there would show up beside the +# versioned artifacts under a version-less name, duplicating what the archive +# already carries. +extra = ["build/webroot/httpd-webroot.img"] [distribution.smp] # One FMID per minor release, spent exactly once: it names a functional level, diff --git a/smp-todo.md b/smp-todo.md index a28d2de..0db5839 100644 --- a/smp-todo.md +++ b/smp-todo.md @@ -80,7 +80,7 @@ nicht aus Werkzeugmangel: Umgesetzt: -- **`make webroot`** baut `dist/httpd-webroot.img` aus `static/` mit einem +- **`make webroot`** baut `build/webroot/httpd-webroot.img` aus `static/` mit einem gepinnten `ufsd-utils` (1 MB = 256 Blöcke, `--owner`/`--group` gesetzt, damit im Artefakt keine Build-Maschinen-Userid steht). `package` und `dist` hängen davon ab, `[distribution] extra` legt es ins Archiv. From dbc27e5ab26568d7c2671beb10b8919b0b105a50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 21:11:08 +0200 Subject: [PATCH 10/11] O1 done: THTP400 is free in the CDS and the ACDS on both stands LIST CDS SYSMOD(THTP400) and LIST ACDS SYSMOD(THTP400), run 2026-08-24 on mvsdev (MVS/CE, JOB01948) and drnmig3a (TK5, JOB00028), both HMASMP LVL 04.48. Each of the four answers RC 04 with "THE FOLLOWING SELECTED ENTRIES WERE NOT FOUND". The FMID is now verified the way TUFS120 and TFTP100 were before their tags -- the earlier SMPPTS scan proved only that nothing had been *received* under the id, while the CDS and ACDS store hashed member names and can only be read with LIST. Two things measured on the way, both recorded in smp-todo.md because they cost time to rediscover: The SMPAPP procstep is HMASMP on both stands and the procedure brings no SMPCNTL of its own, so both //HMASMP.SMPCNTL DD * and the unqualified //SMPCNTL DD * work -- the procedure has a single step. The documented job was right as written. The criterion is the report, not the return code. RC 04 ends every LIST, including one that read no control statements at all; what says the id is free is the SELECT SUMMARY REPORT in SMPOUT. A caller that checks only the job RC cannot tell an empty list from a hit. What is left before the tag is O2, the dry run under TTST400. --- TODO.md | 10 ++++++---- project.toml | 18 +++++++++--------- smp-todo.md | 42 +++++++++++++++++++++++++++--------------- 3 files changed, 42 insertions(+), 28 deletions(-) diff --git a/TODO.md b/TODO.md index fbcad28..e43d2a3 100644 --- a/TODO.md +++ b/TODO.md @@ -40,10 +40,12 @@ and `docs/messages.md` §*A refused start* is where the resulting contract is written down. **What is left before the 4.0.0 tag is not in the tracker at all** — it is the -install package, and [`smp-todo.md`](smp-todo.md) holds it: the `THTP400` check -against CDS and ACDS on both stands (O1), and the dry run under the throwaway -FMID (O2). O3 closed with #252, which put the document root in the archive as a -UFS image; what remains of it is a checksum for the release assets. +install package, and [`smp-todo.md`](smp-todo.md) holds it. One item now: +**O2**, the dry run under the throwaway FMID `TTST400`. O1 closed on +2026-08-24 — `THTP400` answered RC 04 with an empty list in the CDS *and* the +ACDS on both stands — and O3 closed with #252, which put the document root in +the archive as a UFS image; of it only a checksum for the release assets is +left. --- diff --git a/project.toml b/project.toml index f86692b..8201ecb 100644 --- a/project.toml +++ b/project.toml @@ -364,15 +364,15 @@ extra = ["build/webroot/httpd-webroot.img"] # E??nnnn namespace MVS 3.8j's own function SYSMODs occupy (EBB1102 is 3.8j # itself, alongside EAS1102, EBT1102, EDE1102, ...). # -# NOT yet verified the way TFTP100 and TUFS120 were, and the difference matters. -# What is measured is the SMPPTS on mvsdev -- 1544 SYSMODs scanned, no THTP400 -# (smp-todo.md §2) -- and the PTS shows only what was *received*. The CDS and -# ACDS store hashed member names, so LIST CDS SYSMOD(THTP400) and LIST ACDS -# SYSMOD(THTP400) are the only way to see what is actually applied or accepted. -# Both stands (mvsdev, drnmig3a) still have to answer RC 04 with an empty list -# before the 4.0.0 tag. A test install must use a throwaway id -- a -# half-applied FMID leaves this one occupied, and smp-todo.md reserves TTST400 -# for exactly that. +# Verified free the way TFTP100 and TUFS120 were, on both stands, 2026-08-24: +# LIST CDS SYSMOD(THTP400) and LIST ACDS SYSMOD(THTP400) each answered RC 04 +# with "THE FOLLOWING SELECTED ENTRIES WERE NOT FOUND" -- mvsdev (MVS/CE, +# JOB01948) and drnmig3a (TK5, JOB00028), both HMASMP LVL 04.48. That is the +# check that counts: the SMPPTS scan done earlier shows only what was +# *received*, while the CDS and ACDS store hashed member names, so a LIST +# against both zones is the only way to see what is applied or accepted. +# A test install must still use a throwaway id -- a half-applied FMID would +# occupy this one, and smp-todo.md reserves TTST400 for exactly that. fmid = "THTP400" system = "Z038" diff --git a/smp-todo.md b/smp-todo.md index 0db5839..3e67aaa 100644 --- a/smp-todo.md +++ b/smp-todo.md @@ -21,13 +21,9 @@ Dieses Dokument hält nur noch das, was **für httpd offen** ist. ## 1. Offen -### O1 — `THTP400` im CDS und ACDS prüfen · **vor dem 4.0.0-Tag** +### ~~O1 — `THTP400` im CDS und ACDS prüfen~~ · **erledigt 2026-08-24** -Belegt ist bisher nur der **SMPPTS** auf `mvsdev`: 1544 SYSMODs gelesen, kein -`THTP400` (§3). Der PTS zeigt aber nur, was *empfangen* wurde. CDS und ACDS -speichern gehashte Membernamen — ein Namensvergleich dort liefert -Scheinergebnisse, wie in §3 gemessen. Gewissheit gibt nur ein `LIST`-Job, auf -**beiden** Ständen (`mvsdev` = MVS/CE, `drnmig3a` = TK5): +Beide Stände melden die ID frei. Gefahren wurde auf jedem: ``` //LIST EXEC SMPAPP @@ -37,13 +33,28 @@ Scheinergebnisse, wie in §3 gemessen. Gewissheit gibt nur ein `LIST`-Job, auf /* ``` -**RC 04 mit leerer Liste heißt frei.** Der Zonenoperand ist Pflicht; bares -`LIST SYSMODS .` ist SMP/E-Syntax und endet in `HMA2033 SYNTAX ERROR`. Und -qualifizieren: `LIST CDS .` gibt auf MVS/CE 116 000 Zeilen aus. - -Die FMID wird genau einmal vergeben. ufsd (`TUFS120`) und ftpd (`TFTP100`) -haben diesen Job vor ihrem Tag gefahren, httpd noch nicht — der Kommentar in -`project.toml` sagt das auch so. +| Stand | Job | CDS | ACDS | +|---|---|---|---| +| `mvsdev` (MVS/CE, HMASMP LVL 04.48) | `JOB01948` | RC 04, `NOT FOUND` | RC 04, `NOT FOUND` | +| `drnmig3a` (TK5, HMASMP LVL 04.48) | `JOB00028` | RC 04, `NOT FOUND` | RC 04, `NOT FOUND` | + +Damit ist `THTP400` so belegt wie `TUFS120` und `TFTP100` vor ihren Tags — +der SMPPTS-Scan aus §3 zeigte nur *Empfangenes*, CDS und ACDS speichern +gehashte Membernamen, und nur der `LIST`-Job sieht, was wirklich angewendet +oder akzeptiert ist. Der Zonenoperand bleibt Pflicht (bares `LIST SYSMODS .` +ist SMP/E-Syntax → `HMA2033`), und qualifizieren auch: `LIST CDS .` gibt auf +MVS/CE 116 000 Zeilen aus. + +**Zwei Dinge, die dabei gemessen wurden und beim nächsten Mal Zeit sparen:** + +- Der `SMPAPP`-Procstep heißt auf beiden Ständen `HMASMP` und bringt **kein** + `SMPCNTL` mit. Beide Formen funktionieren — `//HMASMP.SMPCNTL DD *` wie + `//SMPCNTL DD *` unqualifiziert, weil die Prozedur nur einen Step hat. +- **Das Kriterium ist der Report, nicht der Returncode.** RC 04 steht am Ende + jeder LIST-Ausführung; die Aussage steckt in `LIST SELECT SUMMARY REPORT` + plus `THE FOLLOWING SELECTED ENTRIES WERE NOT FOUND` im **SMPOUT**. Wer nur + den Job-RC abfragt, kann eine leere von einer treffenden Liste nicht + unterscheiden. ### O2 — Testinstallation mit Wegwerf-FMID `TTST400` @@ -61,8 +72,9 @@ man etwas dafür tun muss: `@VRM@` kommt aus der Projektversion, und lebt also in `HTTPD.V4R0M0D.*`, das Release in `HTTPD.V4R0M0.*`. Aufräumen danach: UCLIN-Job aus `docs/installation.md` §12 mit `TTST400`, dann -die Datasets löschen, dann `LIST CDS/ACDS SYSMOD(THTP400)` — das ist zugleich -O1. +die Datasets löschen, dann denselben `LIST`-Job wie in O1 — diesmal auf +`TTST400`, um zu sehen, dass die Wegwerf-ID wieder weg ist, und auf `THTP400`, +um zu bestätigen, dass der Testlauf sie nicht angefasst hat. ### O3 — UFS-Webroot: entschieden und umgesetzt (Issue #252) From a8a960bfa363e6eb24fae2d039b1eead98e3068d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Gro=C3=9Fmann?= Date: Mon, 24 Aug 2026 21:25:03 +0200 Subject: [PATCH 11/11] O2 done: the install rehearsed end to end under TTST400 and cleaned back off Run on mvsdev from the unpacked httpd-4.0.0-dev-dist.zip -- the artifact an operator downloads -- with fmid temporarily on TTST400 (not committed; project.toml says THTP400 again). alloc JOB01972 CC 0000, LINKLIB + AHTTPLOD created inst JOB01973 all eight steps CC 0000: DELOLD, RECV1, RECV2, RECV, APPLYCHK, APPLY, ACCEPT, CLEANUP list JOB01974 RC 00 in both zones: JCLIN=YES, REC/APP/ACC stamped, MOD = HTTPD HTTPDM HTTPDMTT HTTPDSRV ABEND0C1 uclin JOB01975 CC 0000, inventory cut and datasets scratched list JOB01976 TTST400 gone from the CDS and the ACDS list JOB01977 THTP400 still free -- the rehearsal did not touch it Beyond the return codes it settles four things that were derivation until now: the @VRM@/@LINKLIB@ substitution arrives correctly on the target (the installed HTTPWEBR names HTTPD.V4R0M0D.WEBROOT.UFS, the procedure's STEPLIB names the versioned LINKLIB), SMP copies rather than re-binds, the UCLIN removal path in installation.md 12 works as written, and the -dev VRM keeps the rehearsal clear of both the tagged release and the site's own datasets. Nothing was left behind: mvsdev carries HTTPD.LINKLIB and HTTPD.WWWROOT again, both site content, both untouched. One trap recorded with it: scratch datasets from a job with IDCAMS, never through the REST API -- a DELETE there leaves the ENQ standing and the next DISP=SHR job hangs. --- TODO.md | 14 ++++++------- smp-todo.md | 60 +++++++++++++++++++++++++++++++++++++---------------- 2 files changed, 49 insertions(+), 25 deletions(-) diff --git a/TODO.md b/TODO.md index e43d2a3..4a3c21b 100644 --- a/TODO.md +++ b/TODO.md @@ -39,13 +39,13 @@ exit that could end a refused start `CC 0000`; nothing in that thread is open, and `docs/messages.md` §*A refused start* is where the resulting contract is written down. -**What is left before the 4.0.0 tag is not in the tracker at all** — it is the -install package, and [`smp-todo.md`](smp-todo.md) holds it. One item now: -**O2**, the dry run under the throwaway FMID `TTST400`. O1 closed on -2026-08-24 — `THTP400` answered RC 04 with an empty list in the CDS *and* the -ACDS on both stands — and O3 closed with #252, which put the document root in -the archive as a UFS image; of it only a checksum for the release assets is -left. +**Nothing MVS-side blocks the 4.0.0 tag any more.** The release work was never +in the tracker — it is in [`smp-todo.md`](smp-todo.md) — and as of 2026-08-24 it +is done: `THTP400` is free in the CDS *and* the ACDS on both stands (O1), the +full install was rehearsed under the throwaway FMID `TTST400` and cleaned back +off with UCLIN, every step CC 0000 (O2), and the document root ships as a UFS +image (O3, #252). What is left there is a checksum for the release assets and +O4, a convenience sample nobody is blocked on. --- diff --git a/smp-todo.md b/smp-todo.md index 3e67aaa..b1e1abf 100644 --- a/smp-todo.md +++ b/smp-todo.md @@ -19,7 +19,14 @@ Dieses Dokument hält nur noch das, was **für httpd offen** ist. --- -## 1. Offen +## 1. Stand + +**Vor dem 4.0.0-Tag ist nichts mehr offen, was MVS braucht.** O1 (FMID frei) und +O2 (Generalprobe) sind am 2026-08-24 gefahren, O3 (Webroot) ist mit Issue #252 +umgesetzt. Was bleibt, ist O4 — eine Bequemlichkeitsfrage, keine Blockade — und +die Checksummen aus O3. Die erledigten Punkte bleiben mitsamt Belegen stehen: +sie sind das Protokoll des Release-Laufs, und die nächste Minor-Version fährt +dieselbe Strecke. ### ~~O1 — `THTP400` im CDS und ACDS prüfen~~ · **erledigt 2026-08-24** @@ -56,25 +63,42 @@ MVS/CE 116 000 Zeilen aus. den Job-RC abfragt, kann eine leere von einer treffenden Liste nicht unterscheiden. -### O2 — Testinstallation mit Wegwerf-FMID `TTST400` - -Die Generalprobe aus einem `-dev`-Baum. Ein Testlauf unter `THTP400`, der -abbricht oder halb angewendet wird, belegt genau die ID, die das getaggte 4.0.0 -braucht — und das CDS lässt sich hinterher nur mit `UCLIN` bereinigen -(`docs/installation.md` §12). +### ~~O2 — Testinstallation mit Wegwerf-FMID `TTST400`~~ · **erledigt 2026-08-24** -Mit mbt ist das eine Zeile: `fmid` in `project.toml` auf `TTST400` setzen, -`make package`, installieren — **und die Änderung nie committen**. +Auf `mvsdev` gefahren, aus dem entpackten Archiv (`httpd-4.0.0-dev-dist.zip`), +also genau dem, was ein Betreiber bekommt. `fmid` stand dafür auf `TTST400` — +die Änderung ist **nicht** committet, `project.toml` sagt wieder `THTP400`. -Die Datasetnamen kollidieren dabei nicht mit dem späteren Release, ohne dass -man etwas dafür tun muss: `@VRM@` kommt aus der Projektversion, und -`4.0.0-dev` ergibt `V4R0M0D`, das getaggte `4.0.0` dagegen `V4R0M0`. Der Test -lebt also in `HTTPD.V4R0M0D.*`, das Release in `HTTPD.V4R0M0.*`. - -Aufräumen danach: UCLIN-Job aus `docs/installation.md` §12 mit `TTST400`, dann -die Datasets löschen, dann denselben `LIST`-Job wie in O1 — diesmal auf -`TTST400`, um zu sehen, dass die Wegwerf-ID wieder weg ist, und auf `THTP400`, -um zu bestätigen, dass der Testlauf sie nicht angefasst hat. +| Schritt | Ergebnis | +|---|---| +| XMITs binär hochgeladen (`IBMUSER.HTTPD.LOAD.XMIT`, `…SAMP.XMIT`) | ok | +| `httpd-4.0.0-dev-alloc.jcl` (`JOB01972`) | CC 0000, `LINKLIB` + `AHTTPLOD` angelegt | +| `httpd-4.0.0-dev-inst.jcl` (`JOB01973`), nur die zwei `CHANGE.ME.*` ersetzt | **alle acht Schritte CC 0000**: DELOLD, RECV1, RECV2, RECV, APPLYCHK, APPLY, ACCEPT, CLEANUP | +| `LIST CDS/ACDS SYSMOD(TTST400)` (`JOB01974`) | RC 00, `JCLIN=YES`, REC/APP/ACC gestempelt, `MOD = HTTPD HTTPDM HTTPDMTT HTTPDSRV ABEND0C1` in **beiden** Zonen | +| `HTTPD.V4R0M0D.LINKLIB` / `.AHTTPLOD` | je fünf Module | +| `HTTPD.V4R0M0D.SAMPLIB` | `HTTPD`, `HTTPPRM0`, `HTTPWEBR` | +| `HTTPD.V4R0M0D.HTTPLOAD` | von CLEANUP verschrottet, wie vorgesehen | +| UCLIN + IDCAMS-Scratch (`JOB01975`) | CC 0000 | +| `LIST` danach (`JOB01976`, `JOB01977`) | `TTST400` in beiden Zonen weg, `THTP400` weiterhin frei | + +Nach dem Lauf stehen auf `mvsdev` wieder nur `HTTPD.LINKLIB` und +`HTTPD.WWWROOT` — beides Site-Inhalt, unberührt. + +**Was der Lauf über das Paket beweist**, über die Returncodes hinaus: + +- Die `@VRM@`- und `@LINKLIB@`-Ersetzung kommt richtig auf dem Zielsystem an: + der installierte `HTTPWEBR` sagt `DSN=HTTPD.V4R0M0D.WEBROOT.UFS`, die Proc + `STEPLIB DD DSN=HTTPD.V4R0M0D.LINKLIB`. +- SMP kopiert, statt neu zu binden — die fünf Module stehen nach APPLY im + Ziel und nach ACCEPT in der DLIB. +- Der UCLIN-Weg aus `docs/installation.md` §12 funktioniert wie beschrieben; + er war bis dahin nur hergeleitet, nicht gefahren. +- Die Versionierung trägt: `V4R0M0D` (dev) kollidiert nicht mit dem späteren + `V4R0M0`, und die Site-Platte `HTTPD.WWWROOT` liegt neben allem. + +**Eine Falle, die dabei sichtbar wurde:** Datasets im Aufräumjob per IDCAMS +löschen, nicht über die REST-API — ein `DELETE /zosmf/restfiles/ds/…` lässt das +ENQ stehen, und der nächste `DISP=SHR`-Job hängt. ### O3 — UFS-Webroot: entschieden und umgesetzt (Issue #252)