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(/