Host-Named Site Collections (HNSC) — Operator Guide¶

A Host-Named Site Collection (HNSC) lives at the root of its own host (e.g. https://hr.contoso.com/) instead of at a managed path under a web application's own host (e.g. https://sp.contoso.com/sites/hr). This mirrors real SharePoint's HNSC model.

When to use an HNSC vs. a managed-path site collection¶

	Managed-path SC	HNSC
URL shape	`https://sp.contoso.com/sites/hr`	`https://hr.contoso.com/`
Own DNS record	No (shares the WA's host)	Yes — needs its own A/CNAME
Own TLS SAN entry	No	Yes (see § Certificates)
Typical use	Most sites (departments, teams, projects)	A customer or business unit that needs its own branded hostname

Both live under exactly one parent web application and share that WA's auth, content database pool, and (by default) TLS certificate. A web application can host any mix of managed-path SCs and HNSCs at the same time.

Prerequisites¶

Caller must hold the FarmAdmin role (the CentralAdmin authorization policy — the same gate as every other /_admin/* farm-management endpoint).
The host name must be farm-wide unique — no two HNSCs (or WA host bindings) anywhere in the farm can share a host. Creation/conversion is rejected with 409 HOST_TAKEN / HNSC_INVARIANT otherwise.
Real DNS: point the new hostname at the server (or load balancer) before/at the same time as creating the HNSC — Cesivi does not provision DNS records itself.

Creating a new HNSC¶

Via the Admin UI (/Admin/WebApplicationSettings?name={wa} → Host-Named Site Collections section → Create Host-Named Site Collection form): enter a name, the host header (e.g. hr.contoso.com), optional title/owner/certificate reference, and submit.

Via REST (no PowerShell cmdlet ships for this yet — use the Admin UI or call the endpoint directly):

POST /_admin/webapps/{webAppName}/hnscs
Content-Type: application/json

{
  "name": "hr",
  "host": "hr.contoso.com",
  "title": "HR",
  "owner": "admin",
  "certificateRefOverride": null
}

Returns 201 with the new HNSC's summary, 400 for an invalid/missing name or host, 404 if the web application doesn't exist, 409 if the name or host is already taken.

Converting a managed-path SC → HNSC¶

Via the Admin UI: same section → Convert a Managed-Path Site Collection to HNSC form — pick the existing SC, enter its new host header, and set the 301 redirect grace (days) (default 30; 0 disables the redirect).

Via REST:

POST /_admin/webapps/{webAppName}/sitecollections/{scName}/convert-to-hnsc
Content-Type: application/json

{ "host": "hr.contoso.com", "redirectGraceDays": 30, "certificateRefOverride": null }

This drops the SC's managed-path entry on the parent WA, sets its HostHeader, and — unless redirectGraceDays is 0 or the SC was already at the WA root — records the old URL so requests to it 301-redirect to the new host until the grace period expires (WebApplicationResolutionMiddleware serves the redirect; enforced server-side, no manual DNS/nginx step needed for the redirect itself — only for the new hostname's own DNS record).

Converting an HNSC back → managed-path SC¶

Via the Admin UI: the HNSC table's "→ Managed path" button per row (confirms before submitting).

Via REST:

POST /_admin/webapps/{webAppName}/hnscs/{scName}/convert-to-managed-path
Content-Type: application/json

{ "managedPath": "/sites/hr" }

Omit managedPath to default to /sites/{scName}. Clears the host header, certificate override, and any pending redirect grace, and adds the managed-path entry on the parent WA. 400 if managedPath resolves to / (reserved), 409 if that path is already taken.

Certificates¶

By default an HNSC's TLS certificate is a Subject Alternative Name (SAN) on its parent web application's certificate — the computed SAN list (WA's own hosts ∪ all its HNSC hosts) is exposed on GET /_admin/farm/topology for cesivi-lb / your own cert tooling to consume. Set certificateRefOverride (create or convert-to-hnsc) only when the HNSC needs a dedicated certificate (e.g. a customer-supplied cert or separate CA chain) — this is supported but discouraged; the default single-SAN-cert-per-WA model means one cert renewal covers every HNSC under it automatically. See multi-webapp-ops.md § TLS/HTTP hardening and § Renewing certificates for the certbot/SAN-list mechanics.

Routing precedence¶

Every incoming request's Host: header is checked against the farm-wide HNSC table first; only if no HNSC matches does the web application get resolved by host header and the request path checked against that WA's managed-path table. This means an HNSC host always wins even if it happens to collide with a managed-path prefix on a different WA (it can't, by the farm-wide-uniqueness invariant, but the precedence rule is what makes that invariant necessary).

Reference¶

Cesivi.Server/Controllers/_admin/FarmWebApplicationAdminController.cs — the four HNSC endpoints (GET .../hnscs, POST .../hnscs, POST .../sitecollections/{sc}/convert-to-hnsc, POST .../hnscs/{sc}/convert-to-managed-path).
Cesivi.WebUI/Pages/Admin/WebApplicationSettings.cshtml — the Admin UI panel.
_project/areas/multi-webapp/DESIGN.md §2.7–2.8 — the design rationale (routing precedence, SSL/SAN model).
_project/plans/completed/PLAN-1786-HNSC-Host-Named-Site-Collections.md — the implementation plan and closure note.
multi-webapp-ops.md — TLS hardening, farm PnP/native cmdlets, load-balancer deployment (cesivi-lb discovers HNSC hosts from /_admin/farm/topology).
central-administration.md — Central Administration, which is itself reachable via a dedicated-WA HNSC-style pattern (Mode B) though CA itself is not provisioned through this HNSC surface.