DEV Community: mkt

Restricting rsync to a Specific Directory with authorized_keys

mkt — Tue, 03 Nov 2026 08:29:00 +0000

Introduction

In research environments, sharing large datasets with collaborators over the internet is a common task. This often involves transferring files with scp (which uses sftp under the hood these days) or rsync over SSH with public key authentication. However, simply creating an SSH account for file sharing also allows access to other directories that the account can read or write, as well as shell access and port forwarding. That is not ideal from a security perspective.

A common approach is to configure ChrootDirectory for each user in sshd_config and force the use of internal-sftp. But for tasks such as synchronization, you may still want to use rsync.

In this article, I'll show you a simple way to share files within a specific directory using SSH's authorized_keys and the rsync helper script rrsync (restricted rsync).

Note

This article assumes you are familiar with:

Creating and configuring Linux users

SSH public key authentication

Basic rsync usage

TL;DR

SSH's authorized_keys lets you restrict the commands and features available to each public key.
Setting rrsync as the command in authorized_keys lets you restrict the directory that a client can read from or write to using rsync.

Here are examples of an authorized_keys entry and an rsync command. Adjust the username, public key, paths, command arguments, and other details to suit your environment.

Example: Allow Read-Only Access

An example authorized_keys entry on the server:

# Allow read-only access to /srv/project-x on the server.

restrict,command="/usr/bin/rrsync -ro /srv/project-x" ssh-ed25519 AAAA...

An example rsync command to run on the client:

# Download the files in /srv/project-x/dataset/ on the server to the client's mydataset directory.

user@client:~$ rsync -av \
    -e 'ssh -i ~/.ssh/id_ed25519' \
    user@server:dataset/ \
    ./mydataset/

The path specified by the client is interpreted relative to /srv/project-x, the directory configured on the server. For write-only access, use -wo instead of -ro.

Warning

Depending on the options you use, files may be transferred or deleted unintentionally, particularly when using --delete for uploads. Apply appropriate restrictions in authorized_keys, and check what will happen beforehand with -n (--dry-run).

Test Environment

Ubuntu Server 26.04
rsync 3.4.1 (using the rrsync script included in the rsync package)

Warning

While writing this article, I noticed that the rrsync script included with rsync 3.4.1 appears to have a vulnerability that allows directory restrictions to be bypassed (CVE-2026-53783). For safe use, use version 3.5.1 or later.

authorized_keys and rrsync

Let's briefly look at authorized_keys and rrsync.

authorized_keys

To allow SSH login with public key authentication, add each client public key to the login user's ~/.ssh/authorized_keys file on the server, one key per line.

# Example ~/.ssh/authorized_keys
ssh-ed25519 AAAA...(public-key1)
ssh-ed25519 AAAA...(public-key2)

If a line contains only a public key, the client can use a shell and run commands within the limits of the server configuration and the user's permissions.

You can add options before each public key to restrict the features available when that key is used.

restrict,from="192.0.2.0/24",command="echo 'hello'" ssh-ed25519 AAAA...(public-key3)

restrict: Disables PTY allocation, port forwarding, agent forwarding, X11 forwarding, and execution of ~/.ssh/rc.
from="...": Restricts connections by source IP address or hostname. CIDR notation is also supported.
command="...": Runs the specified command instead of the command requested by the client.

In the example above, PTY allocation and port forwarding are disabled, connections are allowed only from 192.0.2.0/24, and the command that runs is always echo 'hello' (which simply prints hello), regardless of the command the user requests.

There are many other options available in authorized_keys. If you're interested, see the "AUTHORIZED_KEYS FILE FORMAT" section of the sshd man page.

sshd(8) (Ubuntu 26.04)

rrsync

The rsync command synchronizes files between directories. Because it can synchronize data over SSH, it is commonly used for network backups and similar tasks.

Although rsync is often used to synchronize entire directories, you can also transfer individual files by specifying their paths.

There is a helper script for rsync called rrsync (restricted rsync). It is implemented in Python and, as the name suggests, provides a restricted version of rsync. On Ubuntu and some other distributions, the script is included in the rsync package.

By setting rrsync as the command in authorized_keys, you can make only a specific directory available to the client.

Here is the help output for rrsync:

$ rrsync -help
usage: rrsync [-ro | -wo] [-munge] [-no-del] [-no-lock] [-no-overwrite] [-help] DIR

Use "man rrsync" to learn how to restrict ssh users to using a restricted rsync command.

positional arguments:
  DIR            The restricted directory to use.

options:
  -ro            Allow only reading from the DIR. Implies -no-del and -no-lock.
  -wo            Allow only writing to the DIR.
  -munge         Enable rsync's --munge-links on the server side.
  -no-del        Disable rsync's --delete* and --remove* options.
  -no-lock       Avoid the single-run (per-user) lock check.
  -no-overwrite  Prevent overwriting existing files by enforcing --ignore-existing
  -help, -h      Output this help message and exit.

The only required argument is DIR, which specifies the directory to share.

If you set rrsync /srv/project-x as the command in authorized_keys, the client can use rsync to read and write files only within /srv/project-x/.

With this configuration, paths specified by the client are interpreted as follows:

Path specified by the client	Actual path on the server
`user@server:./`	`/srv/project-x/`
`user@server:dataset/`	`/srv/project-x/dataset/`
`user@server:dataset/file.bin`	`/srv/project-x/dataset/file.bin`

Use -ro or -wo to allow only reading or only writing, respectively.

-ro: Allows only reading from the server.
-wo: Allows only writing to the server. On its own, -wo does not prevent existing files from being overwritten or deleted, so combine it with -no-del or -no-overwrite as needed.

The restrictions imposed by rrsync apply on top of normal Linux file permissions. Also, rrsync works by checking paths and options; it does not provide isolation like chroot.

Note

Keep the following points in mind when choosing the shared directory (DIR):

Do not use the user's home directory as DIR. If DIR contains ~/.ssh/authorized_keys or ~/.bashrc and you allow write access, the client could modify those files to bypass the restrictions.

Access outside DIR through symbolic links is also subject to restrictions. rrsync is designed to reject options that dereference symbolic links, such as --copy-links, as well as paths that resolve outside DIR. However, versions affected by the vulnerability mentioned in the Test Environment section may allow these restrictions to be bypassed.

How rrsync Works

rrsync is a Python wrapper script for rsync.

GitHub: RsyncProject / rsync

The command specified by command in authorized_keys receives the command string originally requested by the client in the SSH_ORIGINAL_COMMAND environment variable. rrsync parses this string and starts rsync on the server with the appropriate restrictions.

The main rules for handling paths are:

A path with .. as a component is rejected.
An absolute path starting with / is rewritten relative to DIR. For example, with the configuration above, user@server:/dataset/ refers to /srv/project-x/dataset/.

You could implement similar behavior by checking SSH_ORIGINAL_COMMAND in your own script. Be careful, though: mistakes in path or option handling could allow the restrictions to be bypassed.

Alternative: SFTP + chroot

As a side note...

If you don't specifically need rsync, you can also combine SFTP with ChrootDirectory to restrict access to a particular directory. This is probably the more common approach. In that case, configure the restrictions in the server's sshd_config rather than authorized_keys.

# /etc/ssh/sshd_config
Match User user2
    ChrootDirectory /srv/project-x
    ForceCommand internal-sftp
    DisableForwarding yes
    PermitTTY no

ChrootDirectory: Sets /srv/project-x as the root directory after login. The client sees it as /.
ForceCommand internal-sftp: Prevents commands other than SFTP from running. SCP using SFTP under the hood is also allowed. For read-only access, use internal-sftp -R.

The directory specified by ChrootDirectory and all its parent directories must be owned by root and must not be writable by anyone other than root. If you want to allow uploads, create a separate subdirectory that the user can write to, such as /srv/project-x/upload.

Summary

In this article, I showed how to use SSH's authorized_keys and rrsync to restrict the directory a client can access with rsync.

Beyond the features and commands covered here, there are plenty of useful tools and options that are easy to overlook. Try exploring what might work for your own use case.

References

Change History

2026/11/03: First version.

Personal Blog: https://mkt-sidenotes.dev/tech/2026-10-18-restricting-rsync-to-a-directory-with-authorized-keys/

Moving Away from sudo su (Ubuntu 26.04, sudo-rs)

mkt — Tue, 22 Sep 2026 07:07:54 +0000

TL;DR

Use sudo -i (or sudo -s) instead of sudo su.

In Ubuntu 26.04, the traditional sudo implementation has been replaced by sudo-rs, and signal handling seems to have changed slightly. As a result, if your SSH connection drops while you are running sudo su, the sudo su processes can stay alive indefinitely...

How I Noticed

While setting up an Ubuntu Server 26.04 machine over SSH, I happened to look at the process tree in htop and noticed several sudo su processes running.

None of them were running under tmux; they were all children of PID 1.

What was going on...?

I decided to investigate.

Investigating the Cause

Here's the environment I used for testing:

Ubuntu Server 26.04
sudo-rs (0.2.13-0ubuntu1.2)

Reproducing the Issue

After running a range of tests on an Ubuntu Server 26.04 virtual machine, I confirmed that the sudo su processes stayed alive under the following conditions:

Connect to the server over SSH.
Start a root shell with sudo su.
Force the SSH connection to close by closing the local terminal.

With a reproducible case, I could start narrowing down the cause.

"sudo su" vs. "sudo -i"

While looking into sudo su, I learned that these days, the recommendation is to use sudo -i instead.

I repeated the same test with sudo -i, and no sudo processes remained after the SSH connection closed. That suggested the su part of sudo su was involved.

With a likely cause in mind, I gave ChatGPT access to the virtual machine and asked it to investigate what was happening.

Here's a rough summary of what it found. This is a simplified explanation, not a technically precise one.

When an SSH connection closes, processes such as the shell launched by SSH are notified of the disconnect through SIGHUP. Whether a parent process forwards SIGHUP to its children depends on the implementation, but programs such as sudo and bash do forward it.
With sudo su, su blocks SIGHUP. As a result, the sudo su processes do not exit unless their child process exits on its own (i.e., the bash process running under sudo su stays alive).
With sudo -i, the shell launched by sudo sends SIGHUP to its child process. Once that process exits, sudo -i exits naturally as well.

In other words, it seems that SIGHUP from the SSH disconnect did not terminate sudo su or the processes beneath it. When its parent process exited, sudo su was reparented to PID 1.

"sudo" vs. "sudo-rs"

But I hadn't seen this happen on Ubuntu 24.04 or earlier...

Then I remembered that Ubuntu 26.04 uses sudo-rs as its sudo implementation.

User management — sudo-rs (Ubuntu Server documentation): https://ubuntu.com/server/docs/how-to/security/user-management/#sudo-rs

I switched from sudo-rs back to the traditional sudo implementation and repeated the test. This time, the sudo su processes exited properly when the SSH connection closed.

So it seemed that sudo-rs handled SIGHUP differently from the traditional sudo.

At this point, I asked ChatGPT to look into the implementations of both the traditional sudo (the sudo-project version) and sudo-rs.

From that investigation, it appeared that the traditional sudo has its own logic for cleaning up child processes when the TTY disconnects, while the newer sudo-rs does not currently seem to handle that situation well. I haven't modified either implementation to test this, so I can't be certain.

GitHub sudo-project/sudo exec_pty.c: https://github.com/sudo-project/sudo/blob/1815241c464259564541cc6306e12f2763691d92/src/exec_pty.c#L335-L360
GitHub trifectatechfoundation/sudo-rs, issue "Better handling of closed user tty": https://github.com/trifectatechfoundation/sudo-rs/issues/1379

Summary

The sudo-rs implementation used in Ubuntu 26.04 handles signals differently from the traditional sudo. This seems like a good opportunity to move away from sudo su and use sudo -i (or sudo -s) instead.

You could perhaps call this a bug in sudo-rs. Still, considering that the traditional sudo has extra logic to work around the issue with sudo su, avoiding sudo su may be the safer choice.

That said, seeing sudo su processes linger under PID 1 is still pretty unsettling...

Additional Notes

On Ubuntu 26.04, you can switch between sudo implementations with the following command:

$ sudo update-alternatives --config sudo

There are 2 choices for the alternative sudo (providing /usr/bin/sudo).

  Selection    Path                     Priority   Status
------------------------------------------------------------
* 0            /usr/lib/cargo/bin/sudo   50        auto mode
  1            /usr/bin/sudo.ws          40        manual mode
  2            /usr/lib/cargo/bin/sudo   50        manual mode

Press <enter> to keep the current choice[*], or type selection number:

You can also run either sudo implementation using its absolute path shown above, without changing the system-wide selection.
As a related aside, I learned that nohup deliberately ignores SIGHUP (SIG_IGN), rather than blocking it.

References

User management — sudo-rs (Ubuntu Server documentation): https://ubuntu.com/server/docs/how-to/security/user-management/#sudo-rs
sudo-project/sudo (GitHub): https://github.com/sudo-project/sudo
trifectatechfoundation/sudo-rs (GitHub): https://github.com/trifectatechfoundation/sudo-rs

Change History

2026/09/22: First version.

Personal Blog: https://mkt-sidenotes.dev/ja/tech/2026-09-20-do-not-use-sudo-su-ubuntu-26/

Visualizing Year/Month/Day Progress in Grafana

mkt — Sun, 30 Nov 2025 09:21:51 +0000

As of writing this post (2025/11/30), apparently around 90% of this year has already passed.

// Detect dark theme var iframe = document.getElementById('tweet-1993184119292149949-95'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1993184119292149949&theme=dark" }

I use Grafana and Prometheus for system monitoring, and I thought it would be cool to see "How much of this year has passed?" directly on my Grafana dashboard.

So I built it!

While I was at it, I decided to show not only the progress of this year but also the progress of this month and today.

TL;DR

Here's what the panel looks like:

After some trial and error, I managed to create this using only Grafana and Prometheus (PromQL), which I already use every day.

The PromQL queries to calculate each value (for UTC) are as follows:

This Year (UTC)

(
  ((day_of_year() - 1) * (3600 * 24)) + (time() % (3600 * 24))
)
/
(
  (365 + (day_of_year() != bool day_of_year(vector(time() + 3600 * 24 * 365)))) * 3600 * 24
)

This Month (UTC)

(
  ((day_of_month() - 1) * (3600 * 24)) + (time() % (3600 * 24))
)
/
(
  days_in_month() * (3600 * 24)
)

Today (UTC)

(time() % (3600 * 24)) / (3600 * 24)

If you want to display progress in a timezone other than UTC, simply add the appropriate offset (in seconds) to your queries.

For example:

UTC+9 (Japan Standard Time; JST): add 3600 * 9 (= 32400) seconds
UTC+2: add 3600 * 2 (= 7200) seconds
UTC-5: add 3600 * -5 (= -18000) seconds

Replace the offsets in the queries to match your local timezone.

Below are JST examples:

This Year (JST)

# JST
(
  (day_of_year(vector(time() + 3600 * 9) - 1) * 3600 * 24) + ((time() + 3600 * 9) % (3600 * 24) )
)
/
(
  (365 + (day_of_year(vector(time() + 3600 * 9)) != bool day_of_year(vector(time() + 3600 * 9 + 3600 * 24 * 365)))) * 3600 * 24
)

This Month (JST)

# JST
(
  ((day_of_month(vector(time() + 3600 * 9)) - 1) * (3600 * 24)) + ((time() + 3600 * 9) % (3600 * 24))
)
/
(
  days_in_month(vector(time() + 3600 * 9)) * (3600 * 24)
)

Today (JST)

# JST
((time() + 3600 * 9) % (3600 * 24)) / (3600 * 24)

If you know a better way to do this, let me know 🙇‍♂️

Test Environment

Here's the environment I used for testing:

Ubuntu Server 24.04
- Grafana: 12.3.0
- Prometheus: 2.45.3 (the version available via apt on Ubuntu 24.04)

Note: I used Prometheus 2.x for testing. Things might be simpler with 3.x, but I haven't tried yet.

Calculation Formulas

To visualize how much of today, this month, and this year has passed (which I'll call the "progress"), you need to calculate these values.

The formulas themselves are pretty straightforward: subtract the unixtime at the start of day/month/year from the current unixtime, then divide by the total seconds in day/month/year.

So, if you can express PromQL queries that match the following formulas, you're good to go:

Today’s Progress (%) = \frac{Current Unixtime - Unixtime at Today’s 00:00}{3600 \times 24} \times 100

This Month’s Progress (%) = \frac{Current Unixtime - Unixtime at 00:00 of the 1st Day of Month}{3600 \times 24 \times Days in Month} \times 100

This Year’s Progress (%) = \frac{Current Unixtime - Unixtime at 00:00 of Jan 1st}{3600 \times 24 \times Days in Year} \times 100

Note: I didn't account for daylight saving time (DST) here.

PromQL Queries

Let's implement the formulas above using Prometheus Query Language (PromQL), which provides a number of helpful built-in functions.

Prometheus docs: https://prometheus.io/docs/prometheus/latest/querying/functions/ (Note: Prometheus 2.x and 3.x differ in some literals and syntax. Be careful!)

One thing to keep in mind: PromQL's time functions operate in UTC. If you want values in your local timezone, you must add an offset manually.

The following explanations are a bit log, so if you just want the final queries, feel free to scroll back to the TL;DR section.

Today's Progress

First, let's calculate today's progress.

Today’s Progress (%) = \frac{Current Unixtime - Unixtime at Today’s 00:00}{3600 \times 24} \times 100

In PromQL, you can get the current unixtime by the time() function.

You can also calculate today's 00:00 unixtime using the day_of_year() function, but you don't need to. The number of seconds since 00:00 can be calculated by taking the remainder of the unixtime divided by 86400 (= 3600 * 24).

So we can use modulo directly.

# UTC
(time() % (3600 * 24)) / (3600 * 24)

GitHub Gist: https://gist.github.com/md-irohas/e8289be61c554d0b59fdd36fa085f5fe#file-1_today-progress-utc-promql

If you want to display the value in your local timezone, add the appropriate offset in seconds. For example, for JST (UTC+9), add 3600 * 9 (= 32400) seconds.

# JST
((time() + 3600 * 9) % (3600 * 24)) / (3600 * 24)

GitHub Gist: https://gist.github.com/md-irohas/e8289be61c554d0b59fdd36fa085f5fe#file-2_today-progress-jst-promql

Grafana can multiply by 100 for percentage formatting, so you can leave the raw ratio as-is.

This Month's Progress

Next, this month's progress.

This Month’s Progress (%) = \frac{Current Unixtime - Unixtime at 00:00 of the 1st Day of Month}{3600 \times 24 \times Days in Month} \times 100

Getting the current unixtime is the same as before, but the tricky part is "Unixtime at 00:00 of the 1st Day of Month" and "Days in Month".

Obviously, the number of days in a month varies, so you can't use modulo like I did for today's progress.

Fortunately, PromQL provides the days_in_month() function for the latter.

Then, how do you get the unixtime for the 1st day of the month?

You don't need to calculate it directly. PromQL has a day_of_month() function that returns the current day of the month, so you can write the numerator as:

(day_of_month() - 1) * (3600 * 24)  # Seconds for previous days
+ (time() % (3600 * 24))            # Seconds for today

So, the query for this month's progress looks like this:

# UTC
(
  ((day_of_month() - 1) * (3600 * 24)) + (time() % (3600 * 24))
)
/
(
  days_in_month() * (3600 * 24)
)

GitHub Gist: https://gist.github.com/md-irohas/e8289be61c554d0b59fdd36fa085f5fe#file-3_this-month-progress-utc-promql

For other timezones, you need to make sure day_of_month() and days_in_month() are calculated in your local timezone, not UTC. These functions accept a unixtime (as a vector) as an argument, so you can use your offset-adjusted time.

# JST
(
  ((day_of_month(vector(time() + 3600 * 9)) - 1) * (3600 * 24)) + ((time() + 3600 * 9) % (3600 * 24))
)
/
(
  days_in_month(vector(time() + 3600 * 9)) * (3600 * 24)
)

GitHub Gist: https://gist.github.com/md-irohas/e8289be61c554d0b59fdd36fa085f5fe#file-4_this-month-progress-jst-promql

It's a bit tricky, but it works!

This Year's Progress

Finally, this year's progress.

This Year’s Progress (%) = \frac{Current Unixtime - Unixtime at 00:00 of Jan 1st}{3600 \times 24 \times Days in Year} \times 100

Just like with the month, you can use the day_of_year() function to get the number of seconds since the start of the year:

(day_of_year() - 1) * (3600 * 24) # Seconds for previous days
+ (time() % (3600 * 24))          # Seconds for today

The only missing piece is "Days in Year".

Years normally have 365 days, but leap years have 366. If you've ever taken a programming class, you've probably written an if-else statement to check for leap years. But PromQL doesn't have if-else clause, and there's no handy days_in_year() function.

So, I asked ChatGPT for help, and it suggested the following code:

# PromQL to calculate the number of days in the year
365
+ clamp_max(
  (
    (
      ((floor(vector(time()) / 31557600) + 1970) % 400) == bool 0
    )
    +
    (
      (((floor(vector(time()) / 31557600) + 1970) % 4) == bool 0)
      *
      (((floor(vector(time()) / 31557600) + 1970) % 100) != bool 0)
    )
  ),
  1
)

31557600 represents 365.25 days * 86400 seconds, an approximation for a year. By dividing the unixtime by this value, you can get the year difference since 1970.

Also, you can use the bool modifier to simulate conditional logic. Comparisons return true/false as 1/0, so you can mimic simple if-else behavior.

Interesting... but since it's an approximation, there might be some error (I haven't checked how much it is).

After thinking a bit, I realized we can use PromQL's day_of_year() function to check for leap years. Specifically, if it is a leap year, the length of the year is 366 days, so if you calculate day_of_year() at the same time 365 days ( $= 3600 \times 24 \times 365$ seconds) later, the value must be different from the current value.

So, you can calculate the number of days in the year like this:

# PromQL to calculate if this year has 365 or 366 days
365
+
(
  day_of_year() != bool day_of_year(vector(time() + (3600 * 24 * 365)))   # Returns 1 or 0
)

The final query for this year's progress is:

# UTC
(
  ((day_of_year() - 1) * (3600 * 24)) + (time() % (3600 * 24))
)
/
(
  (365 + (day_of_year() != bool day_of_year(vector(time() + 3600 * 24 * 365)))) * 3600 * 24
)

GitHub Gist: https://gist.github.com/md-irohas/e8289be61c554d0b59fdd36fa085f5fe#file-5_this-year-progress-utc-promql

It's a bit hard to read, but the same logic applies for any timezone. Just adjust the offset in the query to match your local timezone.

# JST
(
  (day_of_year(vector(time() + 3600 * 9) - 1) * 3600 * 24) + ((time() + 3600 * 9) % (3600 * 24) )
)
/
(
  (365 + (day_of_year(vector(time() + 3600 * 9)) != bool day_of_year(vector(time() + 3600 * 9 + 3600 * 24 * 365)))) * 3600 * 24
)

GitHub Gist: https://gist.github.com/md-irohas/e8289be61c554d0b59fdd36fa085f5fe#file-6_this-year-progress-jst-promql

With this, you have all the PromQL queries you need for visualization.

I haven't thoroughly tested all edge cases, so if you spot a bug, please let me know!

Visualizing in Grafana

Once the queries are ready, all that's left is to create your favorite panel in Grafana.

To make a panel like the screenshot above, follow these steps:

Add a new panel to your dashboard.
Select "Bar gauge" as the visualization type.
Choose Prometheus as the data source (assuming you've already added it).
Paste the queries for year, month, and day progress. Set the legend to "This Year", "This Month", and "Today" respectively.
In the right sidebar, configure:
- Bar gauge:
  - Orientation: Horizontal
  - Display mode: Retro LCD
- Standard options:
  - Unit: Misc / Percent (0.0-1.0)
  - Min: 0
  - Max: 1

This should give you a panel that looks like this:

What About Other Datasources?

You can probably do something similar with other datasources, but there are too many to test.

If you use NodeExporter or Pushgateway, you could create your own custom metrics. PostgreSQL can handle pretty complex SQL, so you could probably calculate it there too (though setting up PostgreSQL just for this might be overkill).

Summary

This article walks through how to visualize the progress of year, month, and day using Grafana + Prometheus.

Writing these queries in a DSL like PromQL was a fun little puzzle.

If you try this setup or come up with a cleaner approach, I'd love to hear about it!

References

Prometheus: https://prometheus.io/docs/prometheus/latest/querying/functions/

Changelog

2025/11/30: First version.

Understanding Timestamp Difference between shutdown and systemctl poweroff

mkt — Wed, 22 Oct 2025 09:48:21 +0000

(This is the English translation of my original Japanese post at Zenn.)

I ran into trouble because I didn't properly understand the difference in time formats between the Linux shutdown command and the systemctl poweroff family (same applies to systemctl halt and systemctl reboot).

As a reminder to myself, here's a concise summary of each time format and how they differ.

TL;DR

shutdown -P 06:00 -> (On Ubuntu,) this means the next 6:00. If it's before 6:00 now, that's today at 6:00; if it's already past 6:00, it's tomorrow at 6:00.
systemctl poweroff --when=06:00 -> Today at 6:00; if it's already past that time, it executes immediately.

More examples are in the latter half.

Test environment

Ubuntu Server 24.04 (systemd 255)

My mistake

When managing servers, you'll sometimes want to schedule a shutdown for planned power outages, etc.

The other day, when I tried to run the shutdown command on Ubuntu 24.04, I saw this warning:

$ shutdown --help
... omitted ...

This is a compatibility interface, please use the more powerful 'systemctl reboot',
'systemctl poweroff', 'systemctl reboot' commands instead.

# 'systemctl reboot' appears twice... 🤔
# It's fixed in the latest systemd source.

Ah, so even shutdown is unified by systemd.

So I checked systemctl's man page.

poweroff
    ... omitted ...
    This command honors --force and --when= in a similar way as halt.

So I can use the --when option for scheduling.

Looking at the --when option description:

--when=
    When used with halt, poweroff, reboot, or kexec, schedule the action
    to be performed at the given timestamp, which should adhere to the
    syntax documented in systemd.time(7) section "PARSING TIMESTAMPS".

I didn't feel like reading all of that, so I quickly asked Copilot.

(The original chat is in Japanese)

Me:
Tell me how to write --when option of systemctl poweroff

Copilot:
The --when option in the systemctl poweroff command is used to specify when to power off the system.

Basic syntax
sudo systemctl poweroff --when=

Common options

now: Power off immediately

reboot: Power off on the next reboot

shutdown: Power off on the next system shutdown

Specific time (e.g. 12:30): Power off at the specified time

Examples
sudo systemctl poweroff --when=now
→ Power off immediately
sudo systemctl poweroff --when=20:00
→ Power off at 20:00 today

I thought, okay, same as the shutdown command (THIS WAS THE MISTAKE. Btw, what is reboot or shutdown at a specified time?).
Indeed, the actual shutdown command is a symbolic link to systemctl.

So I assumed that -- just like shutdown -- if I specify the time as 06:00, it would schedule it for 06:00 the next day, and I ran:

$ systemctl poweroff --when="06:00"

Hit Enter, then...

It powered off immediately. 😇

It was just a personal desktop I use casually, so no real harm was done.

What went wrong?

Let's read the systemd.time man page section "PARSING TIMESTAMPS."

... omitted ...

Examples for valid timestamps and their normalized form (assuming the current time was 2012-11-23 18:15:22 and the timezone was UTC+8, for example "TZ=:Asia/Shanghai"):

      Fri 2012-11-23 11:12:13 -> Fri 2012-11-23 11:12:13
      2012-11-23 11:12:13 -> Fri 2012-11-23 11:12:13
      2012-11-23 11:12:13 UTC -> Fri 2012-11-23 19:12:13
      2012-11-23T11:12:13Z -> Fri 2012-11-23 19:12:13
      2012-11-23T11:12+02:00 -> Fri 2012-11-23 17:12:00
      2012-11-23 -> Fri 2012-11-23 00:00:00
      12-11-23 -> Fri 2012-11-23 00:00:00
      11:12:13 -> Fri 2012-11-23 11:12:13
      11:12 -> Fri 2012-11-23 11:12:00    <- here

If you specify only a time, the date is filled in as "today."
If that time has already passed, the action happens immediately.

A bit unfriendly.

How shutdown and systemctl poweroff handle times

shutdown

shutdown [OPTIONS...] [TIME] [WALL...]

TIME can be:

now: immediately
+n: n minutes from now
hh:mm: the next occurrence of hh:mm (24-hour format). For example, 06:30 means the next 06:30 (this works on Ubuntu; other distros may differ).

Also note that the shutdown command can't specify a date.

Examples:

# If you specify nothing, it's 1 minute later
$ shutdown -P

# Immediate
$ shutdown -P now

# The next 06:30 (uses the server's time zone)
$ shutdown -P 06:30

systemctl poweroff

Use the --when option to specify the time.

The time format can include not only time (hh:mm) but also a full datetime and timezone.

If you specify only a time, the date is completed as "today."
If that time has already passed, it executes immediately.

Examples:

# If you specify nothing, it's immediate (differs from shutdown)
$ systemctl poweroff

# Run at 06:30 today; if already past, run immediately
$ systemctl poweroff --when="06:30"

# Run at 06:30 on 2025-10-05
$ systemctl poweroff --when="2025-10-05T06:30:00"

To be safe, avoid time-only strings; specify a full date and time.

Takeaway

Read the official documentation properly.

Notes

Ubuntu 22.04 doesn't have the --when option yet.
You can check how timestamps are parsed with systemd-analyze timestamp "06:30".
On Ubuntu (and possibly elsewhere), shutdown is a symlink to systemctl, but their time formats are not compatible; shutdown is implemented as a compatibility command inside systemctl.

Change history

2025-10-21: Translated from my original Japanese post.