[[urls]]
= Cockpit URLs

Cockpit URLs follow a specific structure, related to the components they
are loading. Various components are loaded in `+<iframe>+` tags. The
URLs for these components are described first. Further down below you
can find information about the top level bookmarkable Cockpit address
URLs.

[[urls-components]]
== Component URLs

Cockpit components are HTML documents. They are organized into
link:#packages[packages]. Each package contains information about which
HTML components are available in that package. Components should always
use relative URLs to access resources, such as images, scripts or CSS
files, even if they refer to a resource in another package.

The following are valid component URLs, each bit will be discussed
below:

....
/cockpit/@localhost/package/component.html#/hash
/cockpit/$checksum/package/component.html#/hash
/cockpit/@server.example.com/package/component.html#/hash
/cockpit+embedder/@localhost/package/component.html#/hash
....

All resource URLs are under the `+/cockpit+` namespace. In cases where a
Cockpit component is being link:#embedding[embedded] the `+/cockpit+`
may be followed by a plus sign and another `+embedder+` specific
identifier.

What follows is either a `+@host+` or `+$checksum+` which tells cockpit
where to link:#packages[find the package]. Checksums are used when more
than one host has identical packages and the resources can be cached.

The `+package+` name is next, followed by the `+component+` HTML path
inside that package. And lastly a hash allows for navigation within a
single component. The hash should follow a URL path and/or query string
form.

[WARNING]
====
Never assume that the `+@host+` or `+$checksum+` portion is predictable.
Only refer to resources in packages on the same host.
====

[[urls-visible]]
== Visible URLs

The above Component URLs are usually not visible to the user. Instead
the Cockpit Web Service wraps the components in a shell which allows
navigation, and provides bookmarkable clean URLs to the component. These
URLs do not affect link:#embedding[embedders] or
link:#packages[components] directly.

If no path is present then the Cockpit will redirect to the default page
for the server.

If the first segment of the path begins with an `+@+` sign, then the
component is being shown from a non-local host.

The next segment of the path, (or first if the component is being shown
on the local host) is the link:#packages[package name]. The remainder of
the path is a component file in the package. If no further path segments
are present, a default `+index.html+` component in the package is
loaded. An extension of `+.html+` is automatically appended.

The hash portion of the path is automatically transferred to the
component as the hash of its link:#urls-components[resource URL].
