Koha Solutions knowledge base: run log of a live check Article https://kohasolutions.com/knowledge-base/koha-opac-per-branch Check scripts/kb/live/koha-opac-per-branch.mjs (SHA-256 03fabc47b66a6e2d4d797fc497408d75a5588caffdb17b8cd204e1292da2ac01) Ran 2026-11-05T16:07:25Z (UTC), 54 s Koha 26.05.02 (Koha::version 26.05.02.002, database version 26.0600002) Source https://git.koha-community.org/Koha-community/Koha/src/commit/d3fc229bc5eaea25dfe88f86149386408fe5d32d System Debian GNU/Linux 13 (trixie) Result PASS: all 28 claims held Each claim is something the article says. "seen" is what the check read back when it is not just a yes/no. Changes the check made to the test server were undone afterwards, as its header describes. == Claims == ok under Plack, SetEnv OPAC_SEARCH_LIMIT alone adds no limit ok OPAC_SEARCH_LIMIT without OPAC_LIMIT_OVERRIDE adds no limit ok the search box on the branch host carries seen: branch:CPL ok the main OPAC host has no limit ok the branch host is titled "Centerville Library catalog" (OVERRIDE_SYSPREF_LibraryName) seen: Centerville Library catalog ok the main host keeps its own LibraryName seen: Koha online catalog ok a disallowed key is logged as "Forbidden/incorrect X-Koha-SetEnv: OPAC_FOO 1" in plack-error.log seen: Forbidden/incorrect X-Koha-SetEnv: OPAC_FOO 1 at /kohadevbox/koha/Koha/Middleware/SetEnv.pm line 95. ok a search from the box is limited to the branch (fewer results than all libraries) seen: box 26, direct 60 ok a direct search URL and the advanced search on the branch host still search every library seen: direct 60, advanced 60 ok an X-Koha-SetEnv header sent by a browser is removed (no limit on the main host) ok the branch host shows CPL's opacheader HTML customization, the main host does not seen: branch true, main false ok a News item for CPL shows on the branch host's home page, not on the main host seen: branch true, main false ok the branch host loads CPL's Specific OPAC CSS, the main host does not seen: branch true, main false ok signed in as a Midway patron on the Centerville host, the Midway header shows instead seen: midway true, centerville false, signed in true ok with OpacAddMastheadLibraryPulldown on, the box shows the library pulldown with Centerville selected and no hidden limit seen: select true, selected branch:CPL, hidden ok a value written with \, keeps its comma: "Centerville, North catalog" seen: Centerville, North catalog ok without the backslash the name is cut at the comma ("Centerville catalog") seen: Centerville catalog ok OPAC_SEARCH_LIMIT branch:multibranchlimit- gives the hidden limit multibranchlimit: seen: multibranchlimit:13 ok a group search finds at least the one-branch count and no more than all libraries seen: group 32, CPL 26, all 60 ok with Plack off, Koha reads SetEnv (MPL) and ignores the header (CPL) seen: branch:MPL ok a2ensite prints "Enabling site zz-library-centerville." and "To activate the new configuration, you need to run:" seen: Enabling site zz-library-centerville. To activate the new configuration, you need to run: service apache2 reload ok apache2ctl graceful prints nothing when it works seen: exit=0 ok apache2ctl -S lists the new name as "port 8080 namevhost centerville.example.org" seen: VirtualHost configuration: *:8081 kohadev-intra.myDNSname.org (/etc/apache2/sites-enabled/kohadev.conf:29) *:8080 is a NameVirtualHost default server kohadev.myDNSname.org (/etc/apache2/sites-enabled/kohadev.conf:4) port 8080 namevhost kohadev.myDNSname.org (/etc/apache2/sites-enabled/kohadev.conf:4) port 8080 namevhost branch.example.org (/etc/apache2/sites-enabled/zz-kbv-branch.conf:1) port 8080 namevhost centerville.example.org (/etc/apache2/sites-enabled/zz-library-centerville.conf:1) ServerRoot: "/etc/apache2" Main DocumentRoot: "/var/www/html" Main ErrorLog: "/var/log/apache2/error.log" Mutex default: dir="/var/run/apache2/" mechanism=default Mutex mpm-accept: using_defaults Mutex watchdog-callback: using_defaults Mutex rewrite-map: using_defaults Mutex proxy: using_defaults PidFile: "/var/run/apache2/apache2.pid" Define: DUMP_VHOSTS Define: DUMP_RUN_CFG Define: ENABLE_USR_LIB_CGI_BIN Define: instance=kohadev User: name="kohadev-koha" id=1000 Group: name="kohadev-koha" id=1000 ok a2dissite prints "Site zz-library-centerville disabled." seen: Site zz-library-centerville disabled. To activate the new configuration, you need to run: service apache2 reload ok with the file named zz-…, apache2ctl -S still names the instance as "default server" seen: default server kohadev.myDNSname.org ok a site file that sorts before the instance file becomes "default server" (it answers the server's IP and unknown names) seen: default server branch.example.org ok …so the main address now serves the branch OPAC (its limit shows on localhost:8080) seen: multibranchlimit:13 ok apache2ctl configtest prints "Syntax OK" seen: Syntax OK == The check that produced this log (scripts/kb/live/koha-opac-per-branch.mjs) == /** * Live check for prisma/ks-kb/100-koha-opac-per-branch.ts (plan48 OPAC customization cluster, child 1). On live Koha * (Plack on, like a package install with `koha-plack --enable`) it adds a second OPAC on port 8080 for * the hostname branch.example.org, and proves: * - plain `SetEnv OPAC_SEARCH_LIMIT` does nothing under Plack; the `RequestHeader add X-Koha-SetEnv` line does; * - OPAC_SEARCH_LIMIT alone does nothing: it needs OPAC_LIMIT_OVERRIDE 1 (masthead.inc); * - the limit is a hidden field in the search box only: a direct URL or the advanced search still searches all; * - a client cannot send the header itself (apache-shared.conf unsets it); * - OPAC_BRANCH_DEFAULT picks that library's HTML customizations and Specific OPAC CSS; a signed-in patron's own * library wins over it; OVERRIDE_SYSPREF_LibraryName renames the catalog for that hostname only; * - a key Koha does not allow is dropped with "Forbidden/incorrect X-Koha-SetEnv" in plack-error.log; * - with OpacAddMastheadLibraryPulldown on, the hidden limit becomes the library pulldown, preselected; * - a library search group: OPAC_SEARCH_LIMIT branch:multibranchlimit-; * - in CGI mode (Plack off) it is the other way round: SetEnv is read, the header ignored; * - a site file that sorts before the instance's file becomes Apache's default server for the port. * Undone: both vhost files (Apache reloaded), the rows it added (additional_contents, library_groups), CPL's * Specific OPAC CSS, the fixture patron's library, the pulldown preference. */ import { spawnSync } from 'node:child_process' export const meta = { koha: '26.05.02', passed: '2026-11-05' } // The article shows this block (with `library` for the instance and its own paths); the check writes the same // lines with the dev box's paths. Keep the five header/SetEnv lines identical to VHOST_ENV_LINES in the article. export const VHOST_ENV_LINES = ` SetEnv OPAC_SEARCH_LIMIT "branch:CPL" SetEnv OPAC_LIMIT_OVERRIDE 1 SetEnv OPAC_BRANCH_DEFAULT "CPL" RequestHeader add X-Koha-SetEnv "OPAC_SEARCH_LIMIT branch:CPL" RequestHeader add X-Koha-SetEnv "OPAC_LIMIT_OVERRIDE 1" RequestHeader add X-Koha-SetEnv "OPAC_BRANCH_DEFAULT CPL" RequestHeader add X-Koha-SetEnv "OVERRIDE_SYSPREF_LibraryName Centerville Library"` const HOST = 'branch.example.org' const SITES = '/etc/apache2/sites-enabled' function vhost({ name, plack = true, env }) { return ` Define instance "kohadev" Include /etc/koha/apache-shared.conf ${plack ? ' Include /etc/koha/apache-shared-opac-plack.conf\n' : ''} Include /etc/koha/apache-shared-opac-git.conf SetEnv PERL5LIB "/kohadevbox/koha:/kohadevbox/koha/lib" DocumentRoot /kohadevbox/koha/koha-tmpl ScriptAlias /cgi-bin/koha/ "/kohadevbox/koha/opac/" ServerName ${name} SetEnv KOHA_CONF "/etc/koha/sites/kohadev/koha-conf.xml" AssignUserID kohadev-koha kohadev-koha ${env} ErrorLog /var/log/koha/kohadev/opac-error.log ` } export default async function run(ctx) { const put = (path, text) => { const r = spawnSync('docker', ['exec', '-i', 'koha-koha-1', 'bash', '-c', `cat > ${path}`], { input: text }) if (r.status !== 0) throw new Error(`write ${path}: ${r.stderr}`) } const reload = () => { ctx.sh('apache2ctl graceful'); ctx.sh('sleep 2') } const files = new Set() ctx.restore('remove the test vhost files and reload Apache', () => { for (const f of files) ctx.sh(`rm -f ${f}`) reload() }) const site = (file, text) => { files.add(file); put(file, text); reload() } const get = (host, path = '/cgi-bin/koha/opac-main.pl', extra = '') => ctx.sh(`curl -s ${extra} ${host ? `-H 'Host: ${host}'` : ''} 'http://localhost:8080${path}'`).out const hiddenLimit = (html) => (html.match(//) ?? [])[1] ?? '' const count = (html) => Number((html.match(/Your search returned (\d+) results/) ?? [])[1] ?? 0) const F = `${SITES}/zz-kbv-branch.conf` // 1. Plain SetEnv, Plack on: nothing reaches Koha. site(F, vhost({ name: HOST, env: ' SetEnv OPAC_SEARCH_LIMIT "branch:CPL"\n SetEnv OPAC_LIMIT_OVERRIDE 1' })) ctx.check('under Plack, SetEnv OPAC_SEARCH_LIMIT alone adds no limit', hiddenLimit(get(HOST)) === '', hiddenLimit(get(HOST))) // 2. Header with the limit but no override: still nothing. site(F, vhost({ name: HOST, env: ' RequestHeader add X-Koha-SetEnv "OPAC_SEARCH_LIMIT branch:CPL"' })) ctx.check('OPAC_SEARCH_LIMIT without OPAC_LIMIT_OVERRIDE adds no limit', hiddenLimit(get(HOST)) === '', hiddenLimit(get(HOST))) // 3. The article's block (both forms, plus the default library, the renamed catalog and a disallowed key). site(F, vhost({ name: HOST, env: `${VHOST_ENV_LINES}\n RequestHeader add X-Koha-SetEnv "OPAC_FOO 1"` })) const branch = get(HOST) ctx.check('the search box on the branch host carries ', hiddenLimit(branch) === 'branch:CPL', hiddenLimit(branch)) ctx.check('the main OPAC host has no limit', hiddenLimit(get(null)) === '', hiddenLimit(get(null))) const title = (branch.match(/([^<]*)<\/title/) ?? [])[1]?.trim() ctx.check('the branch host is titled "Centerville Library catalog" (OVERRIDE_SYSPREF_LibraryName)', title === 'Centerville Library catalog', title) const mainTitle = (get(null).match(/([^<]*)<\/title/) ?? [])[1]?.trim() ctx.check('the main host keeps its own LibraryName', mainTitle !== 'Centerville Library catalog', mainTitle) const warn = ctx.sh('grep -h "Forbidden/incorrect X-Koha-SetEnv: OPAC_FOO 1" /var/log/koha/kohadev/plack-error.log | tail -1').out ctx.check('a disallowed key is logged as "Forbidden/incorrect X-Koha-SetEnv: OPAC_FOO 1" in plack-error.log', warn.includes('Forbidden/incorrect X-Koha-SetEnv: OPAC_FOO 1 at'), warn) // 4. What the limit limits. const viaBox = count(get(HOST, '/cgi-bin/koha/opac-search.pl?q=history&limit=branch:CPL')) const direct = count(get(HOST, '/cgi-bin/koha/opac-search.pl?q=history')) const adv = count(get(HOST, '/cgi-bin/koha/opac-search.pl?advsearch=1&idx=kw&q=history')) ctx.check('a search from the box is limited to the branch (fewer results than all libraries)', viaBox > 0 && viaBox < direct, `box ${viaBox}, direct ${direct}`) ctx.check('a direct search URL and the advanced search on the branch host still search every library', direct === adv && direct > viaBox, `direct ${direct}, advanced ${adv}`) // 5. A client cannot set it. const forged = get(null, '/cgi-bin/koha/opac-main.pl', `-H 'X-Koha-SetEnv: OPAC_SEARCH_LIMIT branch:CPL, OPAC_LIMIT_OVERRIDE 1'`) ctx.check('an X-Koha-SetEnv header sent by a browser is removed (no limit on the main host)', hiddenLimit(forged) === '', hiddenLimit(forged)) // 6. OPAC_BRANCH_DEFAULT: the library's own HTML customization and Specific OPAC CSS. const ids = [] ctx.restore("delete this run's additional_contents rows", () => { if (!ids.length) return ctx.sql(`DELETE FROM additional_contents_localizations WHERE additional_content_id IN (${ids.join(',')})`) ctx.sql(`DELETE FROM additional_contents WHERE id IN (${ids.join(',')})`) ctx.flushCaches() }) const header = (code, branchcode, text) => { ctx.sql(`INSERT INTO additional_contents (category, code, location, branchcode, published_on) VALUES ('html_customizations', '${code}', 'opacheader', '${branchcode}', CURDATE() - INTERVAL 1 DAY)`) const id = ctx.sqlValue(`SELECT MAX(id) FROM additional_contents WHERE code = '${code}'`) ids.push(id) ctx.sql(`INSERT INTO additional_contents_localizations (additional_content_id, title, content, lang) VALUES (${id}, 'Kbverify ${code}', ${ctx.q(`

${text}

`)}, 'default')`) } header('KBVBRCPL', 'CPL', 'Kbverify Centerville header') // a News item for CPL only (opac-main.pl: $homebranch = OPAC_BRANCH_DEFAULT) ctx.sql("INSERT INTO additional_contents (category, code, location, branchcode, published_on) VALUES ('news', 'KBVBRNEWS', 'opac_only', 'CPL', CURDATE() - INTERVAL 1 DAY)") const nid = ctx.sqlValue("SELECT MAX(id) FROM additional_contents WHERE code = 'KBVBRNEWS'") ids.push(nid) ctx.sql(`INSERT INTO additional_contents_localizations (additional_content_id, title, content, lang) VALUES (${nid}, 'Kbverify Centerville news', '

Kbverify news body

', 'default')`) header('KBVBRMPL', 'MPL', 'Kbverify Midway header') // HEX keeps NULL, '' and any text apart (a NULL read through the client comes back as the word "null") const cssHex = ctx.sqlValue("SELECT IFNULL(HEX(opacusercss), 'NULL') FROM branches WHERE branchcode = 'CPL'") ctx.restore("put back CPL's Specific OPAC CSS", () => { ctx.sql(`UPDATE branches SET opacusercss = ${cssHex === 'NULL' ? 'NULL' : cssHex ? `UNHEX('${cssHex}')` : "''"} WHERE branchcode = 'CPL'`) ctx.flushCaches() }) ctx.sql(`UPDATE branches SET opacusercss = '#kbv-cpl { color: #123456; }' WHERE branchcode = 'CPL'`) ctx.flushCaches() const b2 = get(HOST) const m2 = get(null) ctx.check("the branch host shows CPL's opacheader HTML customization, the main host does not", b2.includes('Kbverify Centerville header') && !m2.includes('Kbverify Centerville header'), `branch ${b2.includes('Kbverify Centerville header')}, main ${m2.includes('Kbverify Centerville header')}`) ctx.check("a News item for CPL shows on the branch host's home page, not on the main host", b2.includes('Kbverify Centerville news') && !m2.includes('Kbverify Centerville news'), `branch ${b2.includes('Kbverify Centerville news')}, main ${m2.includes('Kbverify Centerville news')}`) ctx.check("the branch host loads CPL's Specific OPAC CSS, the main host does not", b2.includes('#kbv-cpl { color: #123456; }') && !m2.includes('#kbv-cpl'), `branch ${b2.includes('#kbv-cpl')}, main ${m2.includes('#kbv-cpl')}`) // 7. A signed-in patron's own library wins over OPAC_BRANCH_DEFAULT. const bn = ctx.patron() const home = ctx.sqlValue(`SELECT branchcode FROM borrowers WHERE borrowernumber = ${bn}`) ctx.restore("put the fixture patron back at its library", () => ctx.sql(`UPDATE borrowers SET branchcode = ${ctx.q(home)} WHERE borrowernumber = ${bn}`)) ctx.sql(`UPDATE borrowers SET branchcode = 'MPL' WHERE borrowernumber = ${bn}`) put('/tmp/kbv-pw.pl', `use Koha::Patrons; Koha::Patrons->find(${bn})->set_password({ password => 'Kbverify-Branch-2026', skip_validation => 1 });`) ctx.sh("koha-shell kohadev -c 'perl /tmp/kbv-pw.pl'; rm -f /tmp/kbv-pw.pl") const login = ctx.sh(`J=/tmp/kbv-branch.jar; rm -f $J C=$(curl -s -c $J -H 'Host: ${HOST}' http://localhost:8080/cgi-bin/koha/opac-user.pl | grep -oP 'name="csrf_token" value="\\K[^"]+' | head -1) curl -s -b $J -c $J -o /dev/null -H 'Host: ${HOST}' http://localhost:8080/cgi-bin/koha/opac-user.pl --data-urlencode login_op=cud-login --data-urlencode koha_login_context=opac --data-urlencode "csrf_token=$C" --data-urlencode login_userid=kbreset1 --data-urlencode login_password=Kbverify-Branch-2026 curl -s -b $J -H 'Host: ${HOST}' http://localhost:8080/cgi-bin/koha/opac-main.pl; rm -f $J`).out ctx.check('signed in as a Midway patron on the Centerville host, the Midway header shows instead', login.includes('Kbverify Midway header') && !login.includes('Kbverify Centerville header') && login.includes('opac-main.pl?logout.x=1'), `midway ${login.includes('Kbverify Midway header')}, centerville ${login.includes('Kbverify Centerville header')}, signed in ${login.includes('opac-main.pl?logout.x=1')}`) // 8. The library pulldown replaces the hidden limit and preselects the branch. ctx.setPref('OpacAddMastheadLibraryPulldown', '1') const pd = get(HOST) const sel = (pd.match(/