github.com/pelicanplatform/pelican@v1.0.5/docs/parameters.yaml

#
# Copyright (C) 2023, Pelican Project, Morgridge Institute for Research
#
# Licensed under the Apache License, Version 2.0 (the "License"); you
# may not use this file except in compliance with the License.  You may
# obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

# This file contains structured documentation about the Pelican parameters.
# While it is somewhat human-readable, it is meant to help with the documentation
# generation.

############################
#     Top-Level Configs    #
############################
---
name: ConfigBase
description: >-
  The directory containing the Pelican configurations and data when the utility
  is run as non-root.  Automatically configured; cannot be overridden.
default: "~/.config/pelican"
components: ["*"]
type: filename
---
name: Debug
description: >-
  A bool indicating whether Pelican should emit debug messages in its log.
type: bool
default: false
components: ["*"]
---
name: TLSSkipVerify
description: >-
  When set to true, Pelican will skip TLS verification.  This allows a "man in the middle" attack on the connection but can simplify testing.  Intended for developers.
type: bool
default: false
components: ["origin", "nsregistry", "director"]
---
name: IssuerKey
description: >-
  A filepath to the file containing a PEM-encoded ecdsa private key which later will be parsed
  into a JWK and serves as the private key to sign various JWTs issued by this server

  A public JWK will be derived from this private key and used as the key for token verification
type: filename
root_default: /etc/pelican/issuer.jwk
default: $ConfigBase/issuer.jwk
components: ["client", "nsregistry", "director"]
---
name: Transport.DialerTimeout
description: >-
  Maximum time allowed for establishing a connection to target host.
type: duration
default: 10s
components: ["client", "nsregistry", "origin"]
---
name: Transport.DialerKeepAlive
description: >-
  Maximum time a TCP connection should be kept alive without any activity.
type: duration
default: 30s
components: ["client", "nsregistry", "origin"]
---
name: Transport.MaxIdleConns
description: >-
  Maximum number of idle connections that the HTTP client should maintain in its connection pool.
type: int
default: 30
components: ["client", "nsregistry", "origin"]
---
name: Transport.IdleConnTimeout
description: >-
  Maximum duration an idle connection should remain open in the connection pool.
type: duration
default: 90s
components: ["client", "nsregistry", "origin"]
---
name: Transport.TLSHandshakeTimeout
description: >-
  Maximum time allowed for the TLS handshake to complete when making an HTTPS connection
type: duration
default: 15s
components: ["client", "nsregistry", "origin"]
---
name: Transport.ExpectContinueTimeout
description: >-
  Timeout to control how long the client should wait for the "Expect: 100-continue" response from the server before sending the request
  body.
type: duration
default: 1s
components: ["client", "nsregistry", "origin"]
---
name: Transport.ResponseHeaderTimeout
description: >-
  Maximum time the client should wait for the response headers to be received from the server
type: duration
default: 10s
components: ["client", "nsregistry", "origin"]
---

############################
#     Log-Level Configs    #
############################
name: Logging.Level
description: >-
  A string defining the log level of the client. Options include (going from most info to least): Trace, Debug, Info, Warn, Error, Fatal, Panic.
type: string
default: Error
components: ["*"]
---
name: Logging.LogLocation
description: >-
  A filename defining a file to write log outputs to, if the user desires.
type: filename
default: none
components: ["*"]
---

############################
# Federation-Level Configs #
############################
name: Federation.DiscoveryUrl
description: >-
  A URL pointing to the federation's metadata discovery host.
type: url
default: none
components: ["*"]
---
name: Federation.TopologyNamespaceUrl
description: >-
  A URL containing namespace information for origins and caches configured via the OSG Topology application (a legacy integration). The URL
  should point to the hosted namespace.json.
type: url
osdf_default: https://topology.opensciencegrid.org/stashcache/namespaces.json
default: none
components: ["director", "nsregistry"]
---
name: Federation.TopologyReloadInterval
description: >-
  The frequency, in minutes, that topology should be reloaded.
type: duration
osdf_default: 10
default: none
components: ["director", "nsregistry"]
---
name: Federation.DirectorUrl
description: >-
  A URL indicating where a director service is hosted.
type: url
osdf_default: Default is determined dynamically through metadata at <federation URL>/.well-known/pelican-configuration
default: none
components: ["client", "origin"]
---
name: Federation.NamespaceUrl
description: >-
  A URL indicating where the namespace registry service is hosted.
type: url
osdf_default: Default is determined dynamically through metadata at <federation URL>/.well-known/pelican-configuration
default: none
components: ["client", "director", "origin"]
---
name: Federation.JwkUrl
description: >-
  A URL indicating where the JWKS for the Federation is hosted.
type: url
osdf_default: Default is determined dynamically through metadata at <federtion URL>/.well-known/pelican-configuration
default: none
components: ["client", "origin"]
---

############################
#   Client-Level Configs   #
############################
name: Client.StoppedTransferTimeout
description: >-
  A timeout indicating when a "stopped transfer" event should be triggered.
type: int
default: 100
components: ["client"]
---
name: Client.SlowTransferRampupTime
description: >-
  A duration indicating the rampup period for a slow transfer.
type: int
default: 30
components: ["client"]
---
name: Client.SlowTransferWindow
description: >-
  A duration indicating the sliding window over which to consider transfer speeds for slow transfers.
type: int
default: 30
components: ["client"]
---
name: Client.DisableHttpProxy
description: >-
  A bool indicating whether the client's HTTP proxy should be disabled.
type: bool
default: false
components: ["client"]
---
name: DisableHttpProxy
description: >-
  A legacy configuration for disabling the client's HTTP proxy. See Client.DisableHttpProxy for new config.
type: bool
default: false
components: ["client"]
---
name: Client.DisableProxyFallback
description: >-
  A bool indicating whether the a proxy fallback should be used by the client.
type: bool
default: false
components: ["client"]
---
name: DisableProxyFallback
description: >-
  A legacy configuration for disabling the client's proxy fallback. See Client.DisableProxyFallback for new config.
type: bool
default: false
components: ["client"]
---
name: Client.MinimumDownloadSpeed
description: >-
  The minimum speed allowed for a client download before an error is thrown.
type: int
default: 102400
components: ["client"]
---
name: MinimumDownloadSpeed
description: >-
  A legacy configuration for setting the client's minimum download speed. See Client.MinimumDownloadSpeed for new config.
type: int
default: 102400
components: ["client"]
---

############################
#   Origin-level Configs   #
############################
name: Origin.Url
description: >-
  The origin's configured URL, as reported to XRootD. This is the file transfer endpoint for the origin.

  This Url must not have the same port number as the one in Server.ExternalWebUrl (if any) or Server.WebPort
type: url
default: https://${Server.Hostname}:${Xrootd.Port}
components: ["origin"]
---
name: Origin.ExportVolume
description: >-
  A path to the volume exported by an origin.
type: string
default: none
components: ["origin"]
---
name: Origin.NamespacePrefix
description: >-
  The filepath prefix at which an origin's contents are made globally available, eg /pelican/PUBLIC.
type: string
default: none
components: ["origin"]
---
name: Origin.Multiuser
description: >-
  A bool indicating whether an origin is "multiuser", ie whether the underlying XRootD instance must be configured in multi user mode.
type: bool
root_default: true
default: false
components: ["origin"]
---
name: Origin.EnableCmsd
description: >-
  A bool indicating whether the origin should enable the `cmsd` daemon.
type: bool
default: true
components: ["origin"]
---
name: Origin.SelfTest
description: >-
  A bool indicating whether the origin should perform self health checks.
type: bool
default: true
components: ["origin"]
---
name: Origin.EnableUI
description: >-
  Indicate whether the origin should enable its web UI.
type: bool
default: true
components: ["origin"]
---
name: Origin.EnableIssuer
description: >-
  Enable the built-in issuer daemon for the origin.
type: bool
default: false
components: ["origin"]
---
name: Origin.ScitokensRestrictedPaths
description: >-
  Enable the built-in issuer daemon for the origin.
type: stringSlice
default: none
components: ["origin"]
---
name: Origin.ScitokensMapSubject
description: >-
  Enable the built-in issuer daemon for the origin.
type: bool
default: false
components: ["origin"]
---
name: Origin.ScitokensDefaultUser
description: >-
  Enable the built-in issuer daemon for the origin.
type: string
default: none
components: ["origin"]
---
name: Origin.ScitokensUsernameClaim
description: >-
  Enable the built-in issuer daemon for the origin.
type: string
default: none
components: ["origin"]
---
name: Origin.ScitokensNameMapFile
description: >-
  Enable the built-in issuer daemon for the origin.
type: string
default: none
components: ["origin"]
---
name: Origin.XRootDPrefix
description: >-
  The directory prefix for the xrootd origin configuration files.
type: string
default: origin
components: ["origin"]
---
name: Origin.EnableVoms
description: >-
  Enable X.509 / VOMS-based authentication.  This allows HTTP clients to
  present X.509 client credentials in order to authenticate.  The configuration
  of the authorization for these clients must be done by the admin; Pelican
  does not support automatic VOMS authorization configuration.
type: bool
default: true
components: ["origin"]
---
name: Origin.EnableDirListing
description: >-
  Allows the origin to enable directory listings. Needs to be enabled for recursive
  downloads to work properly and for directories to be visable.
type: bool
default: false
---
name: Origin.Mode
description: >-
  The backend mode to be used by an origin. Current values that can be selected from
  are either "posix" or "s3".
type: string
default: posix
components: ["origin"]
---
name: Origin.S3ServiceName
description: >-
  The S3 Service Name to be used by the XRootD plugin.
type: string
default: none
components: ["origin"]
---
name: Origin.S3Region
description: >-
  The S3 region to be used by the XRootD plugin.
type: string
default: none
components: ["origin"]
---
name: Origin.S3Bucket
description: >-
  The S3 bucket to be used by the XRootD plugin.
type: string
default: none
components: ["origin"]
---
name: Origin.S3ServiceUrl
description: >-
  The S3 service URL to be used by the XRootD plugin.
type: string
default: none
components: ["origin"]
---
name: Origin.S3AccessKeyfile
description: >-
  A path to a file containing an S3 access keyfile for authenticated buckets when an origin is run in S3 mode.
type: filename
default: none
components: ["origin"]
---
name: Origin.S3SecretKeyfile
description: >-
  A path to a file containing an S3 secret keyfile for authenticated buckets when an origin is run in S3 mode.
type: filename
default: none
components: ["origin"]
---


############################
#   Cache-level configs    #
############################
name: Cache.DataLocation
description: >-
  The directory for the location of the cache data files - this is where the actual data in the cache is stored.
  This should *not* be in the same path as XRootD.Mount or else it will expose the data files as part of the files within the cache.
type: string
root_default: /run/pelican/xcache
default: $XDG_RUNTIME_DIR/pelican/xcache
components: ["cache"]
---
name: Cache.ExportLocation
description: >-
  The location of the export directory. Everything under this directory will be exposed as part of the cache. This is
  relative to the mount location.
type: string
default: /
components: ["cache"]
---
name: Cache.XRootDPrefix
description: >-
  The directory prefix for the xrootd cache configuration files.
type: string
default: cache
components: ["cache"]
---
name: Cache.Port
description: >-
  The port over which the xrootd cache should be made available (this will overwrite Xrootd.Port)
type: int
default: 8447
components: ["cache"]
---
name: Cache.EnableVoms
description: >-
  Enable X.509 / VOMS-based authentication for the cache.  This allows HTTP clients
  to present X.509 client credentials in order to authenticate.  The configuration
  of the authorization for these clients must be done by the admin; Pelican
  does not support automatic VOMS authorization configuration.
type: bool
default: false
components: ["cache"]
---

############################
#  Director-level configs  #
############################
name: Director.DefaultResponse
description: >-
  The default response type of a redirect for a director instance. Can be either "cache" or "origin". If a director
  is hosted at https://director.com, then a GET request to https://director.com/foo/bar.txt will either redirect to
  the nearest cache for namespace /foo if Director.DefaultResponse is set to "cache" or to the origin for /foo if
  it is set to "origin".
type: string
default: cache
components: ["director"]
---
name: Director.CacheResponseHostnames
description: >-
  A list of virtual hostnames for the director. If a request is sent by the client to one of these hostnames,
  the director assumes it should respond with a redirect to a cache.

  If present, the hostname is taken from the X-Forwarded-Host header in the request. Otherwise, Host is used.
type: stringSlice
default: none
components: ["director"]
---
name: Director.OriginResponseHostnames
description: >-
  A list of virtual hostnames for the director. If a request is sent by the client to one of these hostnames,
  the director assumes it should respond with a redirect to an origin.

  If present, the hostname is taken from the X-Forwarded-Host header in the request. Otherwise, Host is used.
type: stringSlice
default: none
components: ["director"]
---
name: Director.MaxMindKeyFile
description: >-
  A filepath to a MaxMind API key. The director service uses the MaxMind GeoLite City database (available [here](https://dev.maxmind.com/geoip/docs/databases/city-and-country))
  to determine which cache is nearest to a client's IP address. The database, if not already found, will be downloaded
  automatically when a director is served and a valid key is present.
type: url
default: none
components: ["director"]
---
name: Director.GeoIPLocation
description: >-
  A filepath to the intended location of the MaxMind GeoLite City database. This option can be used either to load
  an existing database, or to configure the preferred download location if Pelican has a MaxMind API key.
type: filename
root_default: /var/cache/pelican/maxmind/GeoLite2-City.mmdb
default: $ConfigBase/maxmind/GeoLite2-city.mmdb
components: ["director"]
---

############################
#  Registry-level configs  #
############################
name: Registry.DbLocation
description: >-
  A filepath to the intended location of the namespace registry's database.
type: filename
root_default: /var/lib/pelican/registry.sqlite
default: $ConfigBase/ns-registry.sqlite
components: ["nsregistry"]
---
name: Registry.RequireKeyChaining
description: >-
  Specifies whether namespaces requesting registration must possess a key matching any already-registered super/sub namespaces. For
  example, if true and a namespace `/foo/bar` is already registered, then registration of `/foo` or `/foo/bar/baz` can only be done
  using keys registered to `/foo/bar`.
type: bool
default: true
components: ["nsregistry"]
---

############################
#   Server-level configs   #
############################
name: Server.TLSCertificate
description: >-
  A filepath to a file containing an X.509 host certificate to use for TLS
  authentication when running server components of Pelican.

  If you override this filepath, you need to provide the matched-pair private key
  via Server.TLSKey and a Certificate Authority (CA) certificate via Server.TLSCACertificateFile
type: filename
root_default: /etc/pelican/certificates/tls.crt
default: "$ConfigBase/certificates/tls.crt"
components: ["origin", "nsregistry", "director"]
---
name: Server.TLSCACertificateFile
description: >-
  A filepath to the TLS Certificate Authority (CA) certificate file, to be used by XRootD
  and internal HTTP client requests.

  Do not override this filepath unless you want to provide your TLS host certifacte
type: filename
root_default: /etc/pelican/certificates/tlsca.pem
default: "$ConfigBase/certificates/tlsca.pem"
components: ["origin", "nsregistry", "director"]
---
name: Server.TLSCACertificateDirectory
description: >-
  A filepath to the directory used for storing TLS Certificate Authority (CA) certificate
  to be used by XRootD only.

  This is exclusive with Server.TLSCACertificateFile for XRootD and this value takes priority
  over Server.TLSCACertificateFile
type: string
default: none
components: ["origin", "nsregistry", "director"]
---
name: Server.TLSCAKey
description: >-
  The name of a file containing a private key corresponding to the TLSCACertificate.
  Used when running server components of Pelican.
type: filename
root_default: /etc/pelican/certificates/tlsca.key
default: "$ConfigBase/certificates/tlsca.key"
components: ["origin", "nsregistry", "director"]
---
name: Server.TLSKey
description: >-
  The name of a file containing a private key corresponding to the TLSCertificate.
  Used when running server components of Pelican.
type: filename
root_default: /etc/pelican/certificates/tls.key
default: "$ConfigBase/certificates/tls.key"
components: ["origin", "nsregistry", "director"]
---
name: Server.WebPort
description: >-
  The port number the Pelican web interface and internal web APIs will be bound to.
type: int
default: 8444
components: ["origin", "director", "nsregistry"]
---
name: Server.WebHost
description: >-
  A string-encoded IP address that the Pelican web engine is configured to listen on.
type: string
default: "0.0.0.0"
components: ["origin", "director", "nsregistry"]
---
name: Server.ExternalWebUrl
description: >-
  A URL indicating the Pelican web interface and internal web APIs address as it appears externally.

  This URL must not have the same port number as the one in Origin.Url (if any) or Xrootd.Port
type: url
default: https://${Server.Hostname}:${Server.WebPort}
components: ["origin", "director", "nsregistry"]
---
name: Server.Hostname
description: >-
  The server's hostname, by default it's os.Hostname().
type: string
default: none
components: ["origin", "director", "nsregistry"]
---
name: Server.IssuerUrl
description: >-
  The URL and port at which the server's issuer can be accessed.
type: string
# Setting default to none for now because it changes based on server type and server mode.
default: none
components: ["origin", "director", "nsregistry"]
---
name: Server.IssuerHostname
description: >-
  The hostname at which the server's issuer can be accessed.
type: string
# Setting default to none for now because it changes based on server type and server mode.
default: none
components: ["origin", "director", "nsregistry"]
---
name: Server.IssuerPort
description: >-
  The port at which the server's issuer can be accessed.
type: int
# Setting default to none for now because it changes based on server type and server mode.
default: none
components: ["origin", "director", "nsregistry"]
---
name: Server.IssuerJwks
description: >-
  A filepath indicating where the server's public JSON web keyset can be found.
type: string
default: none
components: ["origin", "director", "nsregistry"]
---
name: Server.UIActivationCodeFile
description: >-
  If the server's web UI has not yet been configured, this file will
  contain the activation code necessary to turn it on.
type: string
default: $ConfigBase/server-web-activation-code
components: ["origin", "cache", "nsregistry", "director"]
---
name: Server.UIPasswordFile
description: >-
  A filepath specifying where the server's web UI password file should be stored.
type: string
default: $ConfigBase/server-web-passwd
components:  ["origin", "cache", "nsregistry", "director"]
---


################################
#   Issuer's Configurations    #
################################
name: Issuer.TomcatLocation
description: >-
  Location of the system tomcat installation
type: string
default: /opt/tomcat
components: ["origin"]
---
name: Issuer.ScitokensServerLocation
description: >-
  Location of the scitoken server installation
type: string
default: /opt/scitokens-server
components: ["origin"]
---
name: Issuer.QDLLocation
description: >-
  Location of the QDL language and scripts install on the system
type: string
default: /opt/qdl
components: ["origin"]
---
name: Issuer.AuthenticationSource
description: >-
  How users should authenticate with the issuer.  Currently-supported values are:
  - `none` (default): No authentication is performed.  All requests are successful and assumed to
    be a user named `nobody`.
  - `OIDC`: Use the server's OIDC configuration to authenticate with an external identity provider.
type: string
default: OIDC
components: ["origin"]
---
name: Issuer.OIDCAuthenticationRequirements
description: >-
  A list of claim-value pairs that indicate required values from the OIDC ID token to authenticate.
  For example, the following setting:

  ```
  - claim: idp_name
    value: University of Wisconsin-Madison
  ```

  would only allow tokens with `"idp_name": "University of Wisconsin-Madison"` set to authenticate.
type: object
default: []
components: ["origin"]
---
name: Issuer.OIDCAuthenticationUserClaim
description: >-
  The claim in the OIDC ID token to be used as the "username" for the issuer
type: string
default: sub
components: ["origin"]
---
name: Issuer.GroupSource
description: >-
  How the issuer should determine group information based on the authenticated identity.  Valid values are:
  - `none` (default): No group information should be used.
  - `file`: Read groups from an external, JSON-formatted file.  The file should contain a single JSON object
    with keys corresponding to the "user" name and the value a list of strings that are interpretted as the
    user's groups.
type: string
default: none
components: ["origin"]
---
name: Issuer.GroupFile
description: >-
  The location of a file containing group information.  The file should contain a single JSON object with
  keys corresponding to the "user" name and the value a list of strings that are interpretted as the user's
  groups.
type: string
default: none
components: ["origin"]
---
name: Issuer.GroupRequirements
description: >-
  Group membership requirements.  A request must be mapped to one of the groups in this list to successfully
  authenticate.
type: stringSlice
default: []
components: ["origin"]
---
name: Issuer.AuthorizationTemplates
description: >-
  The authorizations that should be generated for an authenticated request.  Value should be a list of
  authorized actions.

  Each action is a key-value pair with the following keys defined:
  - `actions`: A list of authorized actions.  Valid string values are `read`, `modify`, and `create`.
  - `prefix`: A prefix where the actions are authorized.  If the prefix contains the substring `$USER`, the
    string is replaced with the authenticated username.  If the prefix contains the substring `$GROUP`, then
    an authorization is emitted for _each group_ authenticated.

  For example, if the request is authenticated as user `bbockelm` with groups `dept_a` and `dept_b`, then
  the following configuration:

  ```
  - actions: ["read", "create"]
    prefix: /projects/$GROUP
  - actions: ["read", "modify"]
    prefix: /home/$USER
  ```

  will result in the following authorizations:
  - read /projects/dept_a
  - create /projects/dept_a
  - read /projects/dept_b
  - create /projects/dept_b
  - read /home/bbockelm
  - modify /home/bbockelm
type: object
default: []
components: ["origin"]
---

###################################
#   Server's OIDC Configuration   #
###################################
name: OIDC.ClientIDFile
description: >-
  A filepath to a file containing an OIDC Client ID. This is used by the namespace registry to establish OIDC information
  for authenticated registration.
type: filename
root_default: /etc/pelican/oidc-client-id
default: $ConfigBase/oidc-client-id
components: ["nsregistry", "origin"]
---
name: OIDC.ClientID
description: >-
  The OIDC ClientID to use for the server.
type: string
default: none
components: ["nsregistry", "origin"]
---
name: OIDC.ClientSecretFile
description: >-
  A filepath to a file containing an OIDC Client Secret. This is used by the namespace registry to establish OIDC information
  for authenticated registration.
type: filename
root_default: /etc/pelican/oidc-client-secret
default: $ConfigBase/oidc-client-secret
components: ["nsregistry", "origin"]
---
name: OIDC.DeviceAuthEndpoint
description: >-
  A URL describing an OIDC Device Auth Endpoint. This is used by the namespace registry to establish OIDC information
  for authenticated registration.
type: url
default: none
components: ["nsregistry", "origin"]
---
name: OIDC.TokenEndpoint
description: >-
  A URL describing an OIDC Token Endpoint. This is used by the namespace registry to establish OIDC information
  for authenticated registration.
type: url
default: none
components: ["nsregistry", "origin"]
---
name: OIDC.UserInfoEndpoint
description: >-
  A URL describing an OIDC User Info Endpoint. This is used by the namespace registry to establish OIDC information
  for authenticated registration.
type: url
default: none
components: ["nsregistry", "origin"]
---
name: OIDC.AuthorizationEndpoint
description: >-
  A URL containing the OIDC authorization endpoint.
type: url
default: none
components: ["origin"]
---
name: OIDC.Issuer
description: >-
  The URL of the OIDC issuer.  If set, OIDC auto-discovery may be used to find other endpoints (token, user info,
  device auth).
type: url
default: none
components: ["nsregistry", "origin"]
---

############################
#   XRootD-level Configs   #
############################
name: Xrootd.Port
description: >-
  The port over which XRootD should be made available.
type: int
default: 8443
components: ["origin", "cache"]
---
name: Xrootd.RunLocation
description: >-
  A directory where temporary configurations will be stored for the xrootd daemon
  started by the origin or cache.

  For non-root servers, if $XDG_RUNTIME_DIR is not set, a temporary directory will
  be created (and removed on shutdown)
type: filename
root_default: /run/pelican/xrootd
default: $XDG_RUNTIME_DIR/pelican
components: ["origin", "cache"]
---
name: Xrootd.RobotsTxtFile
description: >-
  Origins may be indexed by web search engines; to control the behavior of search
  engines, one may provide local policy via a [robots.txt file](https://en.wikipedia.org/wiki/Robots.txt).

  If this file is not present, it will be auto-created with a default policy of
  blocking all indexing.
type: filename
root_default: /etc/pelican/robots.txt
default: $ConfigBase/robots.txt
components: ["origin"]
---
name: Xrootd.ScitokensConfig
description: >-
  The location of a file configuring xrootd's
  [token-based authorization subsystem](https://github.com/xrootd/xrootd/blob/master/src/XrdSciTokens/README.md).
  This file allows arbitrary changes to the authorization configuration and will be merged with any
  auto-generated configuration; it's recommended for use by experts only.
type: filename
root_default: /etc/pelican/xrootd/scitokens.cfg
default: $ConfigBase/xrootd/scitokens.cfg
---
name: Xrootd.Mount
description: >-
  The mount path for an instance of XRootD.
type: string
default: none
components: ["origin"]
---
name: Xrootd.MacaroonsKeyFile
description: >-
  The filepath to a Macaroons key for setting up authorization in XRootD.
type: string
default: none
components: ["origin"]
---
name: Xrootd.Authfile
description: >-
  The filepath to an auth file for setting up authorization in XRootD.
type: string
default: none
components: ["origin"]
---
name: Xrootd.ManagerHost
description: >-
  A URL pointing toward the XRootD instance's Manager Host.
type: url
default: none
components: ["origin"]
---
name: Xrootd.SummaryMonitoringHost
description: >-
  A URL pointing toward the XRootD instance's Summary Monitoring Host.
type: url
default: none
components: ["origin"]
---
name: Xrootd.DetailedMonitoringHost
description: >-
  A URL pointing toward the XRootD instance's Detailed Monitoring Host.
type: url
default: none
components: ["origin"]
---
name: Xrootd.LocalMonitoringHost
description: >-
  A URL pointing toward the XRootD instance's Local Monitoring Host.
type: url
default: none
components: ["origin"]
---
name: Xrootd.Sitename
description: >-
  The sitename, as configured for XRootD.
type: string
default: none
components: ["origin"]
---

############################
# Monitoring-level configs #
############################
name: Monitoring.DataLocation
description: >-
  A filepath where Prometheus should host its monitoring data.
type: string
root_default: /var/lib/pelican/monitoring/data
default: $ConfigBase/monitoring/data
components: ["origin"]
---
name: Monitoring.PortLower
description: >-
  The lower end of a range of monitoring ports for Prometheus configuration.
type: int
default: 9930
components: ["origin"]
---
name: Monitoring.PortHigher
description: >-
  The lower end of a range of monitoring ports for Prometheus configuration.
type: int
default: 9999
components: ["origin"]
---
name: Monitoring.AggregatePrefixes
description: >-
  A list of path-like prefixes, potentially containing a glob (wildcard character), indicating
  how the Prometheus-based monitoring should aggregate records when reporting.  For example,
  if `/foo/*` is on the aggregate path list, then the monitoring data for a download of
  objects `/foo/bar` and `/foo/baz` will be aggregated into a single series, `/foo`.
type: stringSlice
default: ["/*"]
components: ["origin"]
---
name: Monitoring.TokenExpiresIn
description: >-
  The duration of which the tokens for various Prometheus endpoints expire.

  This includes tokens for director's Prometheus origin discovery endpoint,
  director's origin scraper, and server's self-scraper
type: duration
default: 1h
components: ["origin", "director", "nsregistry"]
---
name: Monitoring.TokenRefreshInterval
description: >-
  The interval of which the token issuer for various Prometheus endpoints
  refreshes the token for monitoring.

  The tokens that are affected by this config are the same as the one in Monitoring.TokenExpiresIn.
  This value must be less than Monitoring.TokenExpiresIn.
type: duration
default: 59m
components: ["origin", "director", "nsregistry"]
---
name: Monitoring.MetricAuthorization
description: >-
  If authorization (Bearer token) is required for accesing /metrics endpoint
type: bool
default: true
components: ["origin", "director", "nsregistry"]
---

############################
#   Plugin-level configs   #
############################
name: Plugin.Token
description: >-
  The specified token for pelican plugin staging
type: string
default: none
components: ["plugin"]
---
name: StagePlugin.Hook
description: >-
  Flag to specify HTCondor hook behavior
type: bool
default: false
components: ["plugin"]
---
name: StagePlugin.MountPrefix
description: >-
  Prefix corresponding to the local mount point of the origin
type: string
default: none
components: ["plugin"]
---
name: StagePlugin.OriginPrefix
description: >-
  Prefix corresponding to the local origin
type: string
default: none
components: ["plugin"]
---
name: StagePlugin.ShadowOriginPrefix
description: >-
  Prefix corresponding to the shadow origin
type: string
default: none
components: ["plugin"]