Skip to Content
Managing Your ServerManaging Server Downtime

Managing Server Downtime

Origin and Cache server administrators can declare downtime periods to signal to the federation that their server will be temporarily unavailable. The Pelican Director uses this information to route data requests away from affected servers during the declared period, minimizing disruptions for end users. Pelican can also set downtime automatically during a graceful shutdown.

Federation administrators can also create or modify downtime for any server in the federation. If you need a downtime set but lack admin access to your own server, see Method 3 below. To see a consolidated view of all active and upcoming downtimes across the federation, visit the Downtime page in the Director web UI.

Graceful Shutdown (Automatic Downtime)

Typically, server administrators set a downtime just before shutting down or restarting a server. Instead of doing this manually, you can rely on Pelican’s “graceful shutdown” feature. It automatically establishes a downtime window under the hood to gracefully drain traffic, minimizing disruption to users’ ongoing transfers.

When Pelican process receives a SIGTERM signal (e.g. via kill -TERM <pid>), or when the “Restart Server” button on web UI is clicked:

  1. Pelican immediately sends a shutdown advertisement to the Director indicating that it is shutting down.
  2. The Director applies an indefinite downtime window to the server, stopping it from redirecting new clients to this Origin/Cache.
  3. Existing in-flight transfers are allowed to continue until Xrootd.ShutdownTimeout (default: 1m) expires and Pelican fully exits.
  4. The downtime remains in effect indefinitely to prevent routing to offline servers, and is automatically cleared whenever the server restarts and sends a regular server ad. This automatic process does not affect any manually configured downtimes set by server or federation administrators.

If you need to schedule downtime for the future, or require a downtime window while the server remains running, use the methods below.

The web interface provides the easiest way to manage downtime. Log in to your server’s web UI with your administrator credentials, then navigate to Downtime (the calendar icon) in the left sidebar.

Add a Downtime

  1. On the Downtime page, click the “CREATE DOWNTIME” button.
  2. Fill in the form:
    • Start Time and End Time — use the date/time pickers. Toggle Unknown Endtime if the end time is unknown.
    • Description — briefly explain why the server is going down.
    • Severity — describes the impact level of the downtime. This field is informational only and does not currently affect how the Director routes traffic; leaving it at the default (Outage) is fine.
  3. Click SUBMIT to save.

Edit a Downtime

Click the pencil icon on an existing downtime card to open the edit form, make your changes, then click SUBMIT.

Delete a Downtime

Click the pencil icon on an existing downtime card to open the edit form, then click the DELETE DOWNTIME button to remove it. The Director will stop routing around that downtime on the next advertisement cycle.

Method 2: CLI (pelican downtime)

The pelican downtime CLI commands interact directly with your server’s admin API and require either local admin access or a valid admin token.

All pelican downtime subcommands accept the following persistent flags:

FlagRequiredDescription
-s / --serverYesWeb URL of your Pelican server (e.g. https://my-origin.example.com:8444)
-t / --tokenNoPath to a token file with downtime scopes (pelican.downtime_create, pelican.downtime_modify, pelican.downtime_delete). Omit to generate automatically (requires access to the server’s issuer key).

List Downtimes

# Show active and future downtimes (default)
pelican downtime list --server https://my-server.example.com:8444
 
# Show all downtimes including past ones
pelican downtime list --server https://my-server.example.com:8444 --status all

Create a Downtime

The create subcommand is interactive — it will prompt you for each field:

pelican downtime create --server https://my-server.example.com:8444

Example session:

Select downtime Class:
1. SCHEDULED
2. UNSCHEDULED
Enter choice number: 1
 
Enter downtime Description: Weekly maintenance window
 
Select downtime Severity:
1. Outage (completely inaccessible)
2. Severe (most services down)
3. Intermittent Outage (may be up for some of the time)
4. No Significant Outage Expected (you shouldn't notice)
Enter number to choose: 1
 
Enter start time in UTC (YYYY-MM-DD HH:MM:SS): 2026-03-10 02:00:00
Enter end time in UTC (YYYY-MM-DD HH:MM:SS) or '-1' for indefinite: 2026-03-10 06:00:00
 
Downtime created successfully: ...

Update a Downtime

The update subcommand is also interactive. Press Enter without typing anything to leave a field unchanged:

pelican downtime update <uuid> --server https://my-server.example.com:8444

Delete a Downtime

pelican downtime delete <uuid> --server https://my-server.example.com:8444

Method 3: Contact the Federation Administrator

If you do not have admin access to your server’s web UI or CLI, you can ask your federation administrator to set a downtime. Federation admins can manage downtime for any registered server in the federation from the Registry web interface.

Provide your federation admin with:

  • Your server’s name
  • The expected start and end times (UTC)
  • A brief description
Running a Site-Local CachePrometheus