There are at the moment no configuration files that can be edited.
TBD
The container runs as an unprivileged user (UID 101) and listens on port 8080.
With Docker:
Example :docker run -d -p 8080:8080 ghcr.io/cobbler/cobbler-web:mainWith Podman:
Example :podman run -d -p 8080:8080 ghcr.io/cobbler/cobbler-web:mainFor enhanced security, the container supports running with a read-only filesystem:
Example :podman run -d -p 8080:8080 \
--read-only \
--tmpfs /tmp:rw,noexec,nosuid,size=64m \
--tmpfs /var/cache/nginx:rw,noexec,nosuid,size=64m \
ghcr.io/cobbler/cobbler-web:mainThe detailed instructions for this are found here: https://github.com/cobbler/charts
The most minimal example is:
helm repo add cobbler https://cobbler.github.io/charts/helm install cobbler/cobbler-web --generate-nameThe Angular-based Web UI is making all connections from the users browser. Without configuration the Web UI is assuming
that the Cobbler Server is reachable at http://localhost/cobbler_api.
To change that please mount a file into the container at /config/app-config.json. This file should have the following
content:
{
"cobblerUrls": ["http://cobbler.example.org/cobbler_api"]
}The setting cobblerUrls is a list of Cobbler server entries, so you can configure multiple Cobbler instances or a
single instance with multiple URLs. Each entry is either a plain string (a URL, meaning password-only login — the
shape shown above) or an object { "url": "...", "authMode": "...", "ssoLoginUrl": "..." } if that particular
server should offer Kerberos/GSSAPI single sign-on. To change the used URL, please log out of the Web UI and log
back in with a different one.
See Kerberos / SSO Login below for the per-server authMode and ssoLoginUrl fields.
Example for Docker/Podman:
Example :podman run -d -p 8080:8080 \
-v $(pwd)/app-config.json:/config/app-config.json:ro \
ghcr.io/cobbler/cobbler-web:<tag>Example for Helm:
Example :---
apiVersion: v1
kind: ConfigMap
metadata:
name: cobbler-web-config-json
data:
app-config.json: |
{
"cobblerUrls": [
"http://cobbler.example.org/cobbler_api"
]
}And the values.yml then contain a paragraph like so:
volumes:
- name: config
configMap:
name: cobbler-web-config-json
volumeMounts:
- name: config
mountPath: /configBy default the Web UI expects to be served at the root of its domain (e.g. https://host/). To serve it
under a path prefix instead (e.g. https://host/cobbler_web/), set the COBBLER_WEB_BASE_PATH environment
variable on the container. It must start with / and must not have a trailing slash, e.g.
/cobbler_web. It should stay a simple path segment (no regex metacharacters), since it is substituted
into the container's nginx configuration. Leaving it unset (the default) preserves the current root
behavior.
With Docker/Podman:
Example :podman run -d -p 8080:8080 \
-e COBBLER_WEB_BASE_PATH=/cobbler_web \
ghcr.io/cobbler/cobbler-web:<tag>With Helm, add to values.yml:
env:
- name: COBBLER_WEB_BASE_PATH
value: /cobbler_webThe container then rewrites its own <base href> and internal redirects to match, so a reverse proxy in
front of it no longer needs to rewrite any HTML — it only needs to forward the subpath through unchanged
(no path stripping). For example, with Apache:
<Location "/cobbler_web/">
ProxyPass "http://127.0.0.1:8080/cobbler_web/"
ProxyPassReverse "http://127.0.0.1:8080/cobbler_web/"
</Location>Note that the /config/app-config.json mount path described above is an internal container path and is
unaffected by COBBLER_WEB_BASE_PATH.
The Web UI can offer a Kerberos/GSSAPI single sign-on login instead of the username/password form, configured
per Cobbler server — one entry in cobblerUrls can use Kerberos SSO while another (in the same dropdown) uses
normal username/password login, e.g. one server for staff on the Kerberos-joined network and another for
external/VPN access via password. A single server is always either password-based or SSO-based, never both. The
browser itself never sees Kerberos tickets: it makes a
withCredentials request to a small ssoLoginUrl endpoint that must be provided by a reverse proxy (or the
Cobbler server itself) sitting in front of the Cobbler backend, using SPNEGO to negotiate with the browser and
returning { "username": ..., "token": ... } on success. Enable it per server via authMode and ssoLoginUrl on
that server's cobblerUrls entry in app-config.json (see Configuration above):
{
"cobblerUrls": [
"https://legacy.example.com/cobbler_api",
{
"url": "https://kerberized.example.com/cobbler_api",
"authMode": "sso",
"ssoLoginUrl": "/cobbler-sso/login"
}
]
}A plain string entry (like "https://legacy.example.com/cobbler_api" above) is shorthand for
{ "url": "...", "authMode": "password" } — password-only, the default/unchanged behavior — so existing
deployments' cobblerUrls lists keep working with zero migration. Mixing password-only and SSO-configured servers
in the same cobblerUrls list is fully supported and expected.
authMode: "password" (default when omitted, or a plain string entry) — password form only; SSO is never
attempted for that server.authMode: "sso" — the manual username/password form is hidden for that server, and an SSO attempt is made
once that server has been selected and confirmed reachable (see below). This is not merely a UI preference — it
reflects a hard backend constraint: the authentication.passthru module required to bridge either supported SSO
backend ignores the submitted username entirely and only checks the password against a server-side shared
secret, and Cobbler loads exactly one authentication module system-wide (no chaining). Once passthru is
configured on that backend, the manual form can never authenticate a real user against it — a single server is
therefore always either password-based or SSO-based, never both. The server field itself stays visible in every
state (it selects which configured Cobbler backend to talk to, not a credential).cobblerUrls entry, a confirmed-reachable SSO attempt fires automatically. With more than one
entry, it does not — the page instead shows a "Sign in via Kerberos" button and waits for the user to click it.
Without this, whichever server was last used (auto-selected from localStorage on load) would silently attempt
SSO before the user has a chance to notice or pick a different server from the dropdown, which is especially
risky when only one of several configured servers uses SSO. The button is only enabled once that server's
reachability check has succeeded, same as the automatic path.The exact SSO bridge that terminates SPNEGO and issues Cobbler tokens depends on which Cobbler backend is fronting the Web UI:
On a release33-line Cobbler server, the SSO bridge is typically implemented as a small CGI/WSGI script fronted
by mod_auth_gssapi in Apache. Two <Location> blocks are needed: one for the SSO bridge endpoint itself, and one
to keep the static Angular app reachable without Kerberos negotiation — the app has to load and run in the
browser before it can call the bridge, so gating the app behind SPNEGO too would create a chicken-and-egg problem.
# Kerberos-protected SSO bridge: negotiates with the browser and mints a Cobbler token.
<Location "/cobbler-sso/login">
AuthType GSSAPI
AuthName "Cobbler SSO"
GssapiCred KRB5_KTNAME:/etc/krb5.keytab
GssapiUseS4U2Proxy off
Require valid-user
ProxyPass "http://127.0.0.1:8081/cobbler-sso/login"
ProxyPassReverse "http://127.0.0.1:8081/cobbler-sso/login"
</Location>
# The static Angular app must stay reachable without Kerberos negotiation so it can load first.
<Location "/">
ProxyPass "http://127.0.0.1:8080/"
ProxyPassReverse "http://127.0.0.1:8080/"
</Location>Matching /config/app-config.json:
{
"cobblerUrls": [
{
"url": "https://cobbler.example.org/cobbler_api",
"authMode": "sso",
"ssoLoginUrl": "/cobbler-sso/login"
}
]
}On the main-line, containerized Cobbler backend, SSO termination is expected to be handled by a Traefik reverse
proxy in front of the cobblerd HTTP API, using Traefik's forwardAuth middleware (or an equivalent SPNEGO-aware
sidecar) backed by a mounted Kerberos keytab, forwarding to an /sso_login route that mints the Cobbler token.
The keytab must be mounted read-only into whichever container performs the GSSAPI negotiation, and the service
principal it contains must match the vhost hostname (see checklist below).
Matching /config/app-config.json:
{
"cobblerUrls": [
{
"url": "https://cobbler.example.org/cobbler_api",
"authMode": "sso",
"ssoLoginUrl": "/sso_login"
}
]
}HTTP/cobbler.example.org@REALM) must exactly match the hostname of the vhost users actually connect to — a
mismatch causes negotiation failures that are easy to misdiagnose as a Web UI bug.Remote-User/X-Remote-User header from the client as the authenticated
identity. Only the identity the auth layer itself establishes during the GSSAPI/SPNEGO exchange is trustworthy;
anything read from a request header can be spoofed by a client that reaches the bridge directly.ssoLoginUrl same-origin. The SSO request is made with withCredentials: true, so ssoLoginUrl
should be a root-relative path (e.g. /sso_login) served from the same origin as the Web UI, not a
cross-origin URL — combining cross-origin requests with credentials widens the attack surface unnecessarily.authMode: "sso" hides the
manual login form entirely for that server entry, because the backend's passthru-based design makes it
non-functional for real users regardless of authMode (see above). Off-domain or non-Kerberos clients selecting
that server will see the SSO "unavailable"/"error" message with no way to log in manually — confirm the
Kerberos/SPNEGO happy path actually works for your intended user population before enabling authMode: "sso"
on a server entry in production, since there is no fallback to fall back on for that server. Keep a plain-string
(password-only) entry alongside it in cobblerUrls if some users need a
non-Kerberos path.sessionStorage
-backed flag that the very next load of the login page consumes: that one load does not auto-attempt SSO. The
manual form itself only changes for an SSO-configured server, where it stays hidden as a substitute — it
would still be non-functional there. For an SSO-configured server, the page shows an explicit "You have been
logged out" message. Both its wording and its recovery button adapt to how many servers are configured: with
only one cobblerUrls entry (where the server field itself is hidden, since there's nothing to pick) it invites
reloading via a "Reload page" button; with more than one entry it instead mentions picking a different server
from the dropdown, which stays visible and functional throughout, and shows the same "Sign in via Kerberos"
button used elsewhere (see below) rather than "Reload page" — clicking it re-attempts SSO directly, bypassing
the suppression flag for that one explicit click (the flag only ever suppresses automatic re-attempts, never a
user's explicit request to sign back in). A password-only server shows the same generic "You have been logged
out" message too (with its fully functional form still visible underneath) purely so the login form's size
doesn't visibly change as the user browses between an SSO-configured and a password-only entry in the server
dropdown right after logging out. The flag is cleared as soon as it's read, so a subsequent reload or navigation
resumes normal automatic SSO behavior.In a production environment this should not be an issue as the Cobbler backend is supposed to have the header
Access-Control-Allow-Origin=*. Please verify if this header is present if you encounter issues.
The issue of CORS cannot be solved inside the Web UI, as such each administrator must debug and fix these issues for their own setup.