AUTOSUSPEND.CONF(5)

📦
version 10.1.0 · 7 versions
, in ubuntu stonking

💖 NAME 💖

autosuspend.conf — this is the config file for autosuspend, and this page is its full documentation. Bestie, everything you need is right here. 🫶

✨ SYNOPSIS ✨

/etc/autosuspend.conf

🎀 GENERAL CONFIGURATION 🎀

This whole section configures the autosuspend daemon itself. She's the main character, periodt. 👑

📄 Configuration file

✍️ Syntax

The autosuspend config file uses INI syntax, and it has to be processable by Python's configparser module (https://docs.python.org/3/library/configparser.html). That's the vibe check it needs to pass, no cap.

A simple configuration file could look like this:

[general]
interval = 30
idle_time = 900
suspend_cmd = /usr/bin/systemctl suspend
wakeup_cmd = echo {timestamp:.0f} > /sys/class/rtc/rtc0/wakealarm
notify_cmd_wakeup = su myuser -c notify-send -a autosuspend 'Suspending the system. Wake up at {iso}'
notify_cmd_no_wakeup = su myuser -c notify-send -a autosuspend 'Suspending the system.'

[check.Ping]
enabled = false
hosts = 192.168.0.7

[check.RemoteUsers]
class = Users
enabled = true
name = .*
terminal = .*
host = [0-9].*

[wakeup.File]
enabled = True
path = /var/run/autosuspend/wakeup

So the file is giving: one [general] section that holds the general processing options, plus as many sections shaped like [check.*] and [wakeup.*] as you want. Those sections are literally the activity checks and wake up checks that get executed. It's giving organized. 💅

⚙️ General configuration

The [general] section holds the options that control the overall behavior of the autosuspend daemon. Here they are, bestie:

  • interval — how long to wait, in seconds, after all the checks have been executed. Chill time. 😌
  • idle_time — the amount of time in seconds with zero detected activity that the host needs to rack up before it gets suspended. Default: 300 seconds.
  • min_sleep_time — the minimal amount of time in seconds the system actually has to sleep for the suspension to really count as triggered. If a scheduled wake up would make the effective sleep time come in under this value, the system just won't sleep at all. Default: 1200 seconds.
  • wakeup_delta — wake the system up this many seconds earlier than the time that was determined for an event that needs the system awake. It's basically a safety margin for how long the wake up actually takes. Default: 30 seconds. Gotta build in that buffer. ⏰
  • suspend_cmd — the command to run when the host is supposed to be suspended. This line can also carry extra command line arguments for the command being executed. 🛌
  • wakeup_cmd — the command to run to schedule a system wake up. The string you give gets processed with Python's str.format() (/usr/share/doc/python3-doc/html/library/stdtypes.html#str.format), and a format argument called timestamp encodes the UTC timestamp of the planned wake up time (as a float). You can also use iso to grab that timestamp in ISO 8601 format. ✨
  • notify_cmd_wakeup — a command to run before the system is about to suspend, purely to notify interested clients. This one is only called when a wake up is scheduled. The string gets processed with Python's str.format() (/usr/share/doc/python3-doc/html/library/stdtypes.html#str.format), and a format argument called timestamp encodes the UTC timestamp of the planned wake up time (float). You can also use iso to get that timestamp in ISO 8601 format. If it's empty or not specified, no command gets called. 📣
  • notify_cmd_no_wakeup — same deal, a command to run before the system is about to suspend to notify interested clients, but this one is only called in the case where NO wake up is scheduled. Which means no string formatting options are available here, at all. If it's empty or not specified, no command gets called.

🔍 Activity check configuration

Every activity check you want to run needs its own section named in the format [check.*]. Each check has a name and an executing class that implements the behavior. The part of the section name after check. decides the name — and, if there's no class option inside the section, it also decides the class that implements the check. But if you do specify the class option, then the name is completely up to you, and the same check can even be instantiated multiple times under different names. Reuse era. ♻️

For every check, these generic options can be specified:

  • class — the name of the class implementing the check. If the name doesn't contain a dot (.), it's assumed to be one of the checks that autosuspend provides internally. Otherwise, this is how you pull in third-party checks. If this option isn't specified, then the section name has to represent a valid internal check class.
  • enabled — has to be true for a check to actually execute. If it's not specified, false is assumed. Sorry bestie, off by default. 🙈

And on top of that, each check might have its own custom options. Customization, we love to see it.

⏰ Wake up check configuration

Wake up checks use the exact same configuration logic as the activity checks described right above. The only difference? The config file sections start with wakeup. instead of check..

For the options of individual checks, go peek at Available activity checks (#available-checks) and Available wake up checks (#available-wakeups).

🔥 AVAILABLE ACTIVITY CHECK 🔥

🦋 Available activity checks

These are the activity checks that are currently implemented, and each one gets described with its available configuration options and the optional dependencies it needs. Let's go. 🌈

🗓️ ActiveCalendarEvent

Checks an online iCalendar file (https://tools.ietf.org/html/rfc5545) for events that are running right now. If one is running, that counts as activity and stops the system from suspending. So basically you can hand it a calendar of times when the system should absolutely not go to sleep. And if that calendar lives on an online service, like a groupware, you might even be able to invite the system to stuff. Iconic, tbh. 💌

Options

  • url — the URL to query for the iCalendar file.
  • timeout — timeout for executed requests, in seconds. Default: 5.
  • username — optional user name used to authenticate at a server that requires authentication. If you use this, you have to provide a password too.
  • password — optional password used to authenticate at a server that requires authentication. If you use this, you have to provide a user name too.

Requirements

🔌 ActiveConnection

Checks whether there's currently a client connected to a TCP server on certain ports. Use it to block suspending when, say, SSH users are connected or a web server has clients on it. Protection mode: activated. 🛡️

Options

  • ports — a list of comma-separated port numbers.

Requirements

  • None. Zero extra deps, we love a low-maintenance queen. 🎀

💻 ExternalCommand

Executes an arbitrary command. If that command returns 0, the system is assumed to be active.

The command is executed as is using shell execution.

⚠️ Bestie, beware of malicious commands hiding in configuration files you obtained from somewhere. Shell execution does not play. 💀

See also:

  • External command scripts for activity detection (#external-command-activity-scripts) for a collection of user-provided scripts for some common use cases.

Options

  • command — the command to execute, including all its arguments.

Requirements

  • None. Nothing extra required. ✨

🧭 JsonPath

A generic check that queries a URL you configure and expects the reply to contain JSON data. The returned JSON document gets checked against a JSONPath (https://goessner.net/articles/JsonPath/) expression you configure, and if the expression matches, the system is assumed to be active.

Options

  • url — the URL to query for the XML reply.
  • jsonpath — the JSONPath (https://goessner.net/articles/JsonPath/) query to execute. If it returns a result, the system is assumed to be active.
  • timeout — timeout for executed requests, in seconds. Default: 5.
  • username — optional user name used to authenticate at a server that requires authentication. If you use this, you have to provide a password too.
  • password — optional password used to authenticate at a server that requires authentication. If you use this, you have to provide a user name too.

Requirements

📺 Kodi

Checks whether an instance of Kodi (https://kodi.tv/) is currently playing.

Options

  • url — base URL of the JSON RPC API of the Kodi instance, default: http://localhost:8080/jsonrpc
  • timeout — request timeout in seconds, default: 5
  • username — optional user name used to authenticate at a server that requires authentication. If you use this, you have to provide a password too.
  • password — optional password used to authenticate at a server that requires authentication. If you use this, you have to provide a user name too.
  • suspend_while_paused — also suspend the system when media playback is paused, instead of only suspending when playback is fully stopped. Default: false

Requirements

🕹️ KodiIdleTime

Checks whether there's been any interaction with the Kodi user interface recently. This keeps the system from suspending while someone is browsing collections and whatnot. It's redundant with XIdleTime on systems running an X server, but it might genuinely be necessary when Kodi is used standalone. Heads up though: it does not replace the Kodi check, because the idle time doesn't get updated while media is playing. Two different jobs, two different checks. 💫

Options

  • idle_time — marks the system active if a user interaction has appeared within this amount of seconds up until now. Default: 120
  • url — base URL of the JSON RPC API of the Kodi instance, default: http://localhost:8080/jsonrpc
  • timeout — request timeout in seconds, default: 5
  • username — optional user name used to authenticate at a server that requires authentication. If you use this, you have to provide a password too.
  • password — optional password used to authenticate at a server that requires authentication. If you use this, you have to provide a user name too.

Requirements

🦋 LastLogActivity

okay so this one literally reads a log file and goes "bestie, when was the last thing that happened in here?" ✨ It uses the most recent time contained in the file to figure out whether you're active or not.

Here's the tea on how it actually works: the lines in the log file get iterated from the back until a line matching a configurable regular expression turns up. That expression is then used to extract the timestamp hiding inside that log line, and that timestamp gets compared to the current time, allowing for a certain delta. 👑

Super important deets: this check only looks at the first line from the back that contains a timestamp. The further lines? Ignored, periodt, don't even worry about them. A typical use case for this check would be a web server access log file. 🌸

This check supports all the date formats that the dateutil parser supports: https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.parse

🎀 Options

  • log_file — path to the log file that should be analyzed
  • pattern — a regular expression used to decide whether a line of the log file even contains a timestamp worth looking at 👀. The expression must contain exactly one matching group. For instance, ^\[(.*)\] .*$ might be used to find dates sitting in square brackets at the beginning of a line.
  • minutes — how many minutes a log file timestamp is allowed to be in the past for activity to be detected. If a timestamp is older than <now> - <minutes>, no activity is detected. default: 10
  • encoding — the encoding with which to parse the log file. default: ascii
  • timezone — the timezone to assume in case a timestamp extracted from the log file has no associated timezone information. Timezones are expressed using the names from the Olson timezone database (e.g. Europe/Berlin). default: UTC

Requirements

🌸 Load

Checks whether the system load is below a certain value. That's it, that's the whole vibe. 😌

🎀 Options

  • threshold — a float for the maximum allowed load value, default: 2.5

Requirements

Nothing listed here bestie, this one's self-sufficient. 🫶

💜 LogindSessionsIdle

Prevents suspending in case IdleHint for one of the running logind sessions is set to no. (logind lives over here: https://www.freedesktop.org/wiki/Software/systemd/logind/)

Heads up bestie 🙈 — support for setting this hint currently varies greatly across display managers, screen lockers, etc. So like, actually check whether the hint is even set on your system, via loginctl show-session. Don't just assume. 💅

🎀 Options

  • types — a comma-separated list of session types to inspect for activity. The check ignores sessions of other types. Default: tty, x11, wayland
  • states — a comma-separated list of session states to inspect. For instance, lingering sessions used for background programs might not be of interest. Default: active, online
  • classes — a comma-separated list of session classes to inspect. For instance, greeter sessions used by greeters such as lightdm might not be of interest. Default: user

🎧 Mpd

Checks whether an instance of MPD is currently playing music. (MPD: http://www.musicpd.org/) If the tunes are bumping, no suspending. 🔥

🎀 Options

  • host — Host containing the MPD daemon, default: localhost
  • port — Port to connect to the MPD daemon, default: 6600
  • timeout — Request timeout in seconds, default: 5

Requirements

🌈 NetworkBandwidth

Checks whether more network bandwidth is currently being used than specified. A set of specified interfaces gets checked one by one, based on the average bandwidth on that particular interface. This average is based on the global checking interval specified in the configuration file via the interval option. 📶

Note: This check assumes stable network interface names. If that's not the case on your system, consider adding the required udev rules to ensure persistent device names. The Archlinux Wiki page on network configuration explains the necessary steps: https://wiki.archlinux.org/title/Network_configuration#Change_interface_name

🎀 Options

  • interfaces — Comma-separated list of network interfaces to check
  • threshold_send <byte/s> — If the average sending bandwidth of one of the specified interfaces is above this threshold, then activity is detected. Specified in bytes/s, default: 100
  • threshold_receive <byte/s> — If the average receive bandwidth of one of the specified interfaces is above this threshold, then activity is detected. Specified in bytes/s, default: 100

Requirements

None listed, so nothing extra to install here. ✨

📡 Ping

Checks whether one or more hosts answer to ICMP requests. Like, are you there? hello? 🫶

🎀 Options

  • hosts — Comma-separated list of host names or IPs.

Requirements

Nothing listed for this one either. 🎀

🧚 Processes

If currently running processes match an expression, the suspend will be blocked. You might use this to hinder the system from suspending when, for example, your rsync runs. Iconic behaviour honestly. 👑

🎀 Options

  • processes — list of comma-separated process names to check for

Requirements

Empty. No requirements listed. 💅

🍓 Smb

Any active Samba connection will block suspend. Simple as that. 🛑

🎀 Options

  • smbstatus — executable needs to be present.

Requirements

Nothing listed here. 🌸

👑 Users

Checks whether a user currently logged in at the system matches several criteria. All provided criteria must match to indicate activity on the host — no partial credit, all or nothing bestie. 💖

To find the applicable values for a given scenario on a system, use the following command:

$ python3 -c "import psutil; print(psutil.users())"
[suser(name='someone', terminal='tty7', host='', started=1670269568.0, pid=77179)]

🎀 Options

All regular expressions are applied against the full string. Capturing substrings needs to be explicitly enabled using wildcard matching. iykyk 👀

  • name — A regular expression specifying which users to capture, default: .*.
  • terminal — A regular expression specifying the terminal on which the user needs to be logged in, default: .*.
  • host — A regular expression specifying the host from which a user needs to be logged in. Users logged in locally on the machine are usually reported with an empty string as the host value. In case this check should only match local users, use ^$ as the value for this option. default: .* (i.e. accept users from any host).

Requirements

Nothing listed. 🦋

✨ XIdleTime

Checks whether all active local X displays have been idle for a sufficiently long time. 🌙

Now, figuring out which X11 sessions currently exist on a running system is a harder problem than one might expect — sometimes the server runs as root, sometimes under the real user, and there are many other configuration variants floating around. So multiple sources for active X server instances are implemented for this check, each of them having different requirements and limitations. You can swap between them with the config option below. 🎀

🎀 Options

  • timeout — required idle time in seconds
  • method — The method to use for acquiring running X sessions. Valid options are sockets and logind. The default is sockets.
    • sockets — Uses the X server sockets files found in /tmp/.X11-unix. This method requires that all X server instances run with user permissions and not as root.
    • logind — Uses logind (https://www.freedesktop.org/wiki/Software/systemd/logind/) to obtain the running X server instances. This does not support manually started servers.
  • ignore_if_process — A regular expression to match against the process names executed by each X session owner. In case the user has a running process that matches this expression, the X idle time is ignored and the check continues as if there was no activity. This can be useful in case of processes which inevitably tinker with the idle time. 🙈
  • ignore_users — Do not check sessions of users matching this regular expressions.

🧁 XPath

A generic check which queries a configured URL and expects the reply to contain XML data. The returned XML document gets checked against a configured XPath expression (https://www.w3.org/TR/xpath/), and in case the expression matches, the system is assumed to be active. 💅

Some common applications and their respective configuration are:

http://127.0.0.1:9981/status.xml

In case you want to prevent suspending when there are active subscriptions or recordings, use the following XPath:

/currentload/subscriptions[number(.) > 0] | /currentload/recordings/recording/start

If you have a permanently running subscriber like Kodi (https://kodi.tv/), increase the 0 to 1. 🔥

http://127.0.0.1:32400/status/sessions/?X-Plex-Token={TOKEN}

Where acquiring the token is documented here: https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/

If suspending should be prevented in case of any activity, this simple XPath expression will suffice:

/MediaContainer[@size > 2]

🎀 Options

  • url — The URL to query for the XML reply.
  • xpath — The XPath query to execute. In case it returns a result, the system is assumed to be active.
  • timeout — Timeout for executed requests in seconds. Default: 5.
  • username — Optional user name to use for authenticating at a server requiring authentication. If used, also a password must be provided.
  • password — Optional password to use for authenticating at a server requiring authentication. If used, also a user name must be provided.

Requirements

✨ AVAILABLE WAKEUP CHECK ✨

🌸 Available wake up checks 🌸

okay bestie, here's the tea: these are all the checks for wake up times that are currently implemented. Each one gets its own lil description with the configuration options it takes and the optional dependencies you might need. no gatekeeping 💅

📅 Calendar

It figures out the next wake up time from an iCalendar file — you know, the RFC 5545 kind (https://tools.ietf.org/html/rfc5545). The next event that starts after the current time? That gets picked as the next wake up time. slay. ✨

🚨 bestie listen: updates to the calendar can only be reflected if the system is currently running. If you change the calendar while the system is asleep, it will obviously not trigger an earlier wake up. it's giving "you snooze you lose" fr fr 😭

Options

  • url — the URL you're querying for that XML reply 📡
  • username — optional user name, for when you're authenticating at a server that requires auth. If you use it, you must also give a password. they come as a pair, no solo acts 💑
  • password — optional password for that same auth situation. If you use it, you must also give a user name. (see above, it's a two-hander 🫶)
  • xpath — the XPath query to execute. It must always return number strings or nothing. no middle ground, periodt ⭐
  • timeout — timeout for executed requests, in seconds. Default: 5. ⏱️

Requirements

🖥️ Command

Determines the wake up time by calling an external command. The command always has to succeed — no ifs, ands, or buts. And if the command prints anything on stdout, that output has to be the next wake up time in UTC seconds. 👑

The command is executed as-is, using shell execution. Which means… 👀

💀 BEWARE of malicious commands in obtained configuration files. like, seriously. that's not a drill, that's a whole vibe check failure waiting to happen. stay safe out there bestie 🙈

Options

  • command — the command to execute, including all arguments 🔥

📄 File

Determines the wake up time by reading a file from a configured location. The file has to contain the planned wake up time as an int or a float, in seconds UTC. 🧮

Options

  • path — path of the file to read, in case it is present 📁

🔁 Periodic

Always schedules a wake up at a specified delta from now on. This is the one you use to let the system wake up every once in a while — for instance, to refresh the calendar that the Calendar check uses. iconic behaviour honestly 🔄✨

Options

  • unit — a string saying which unit the delta is specified in. Valid options are: microseconds, milliseconds, seconds, minutes, hours, days, weeks 🕐
  • value — the value of the delta, as an int 🔢

⏲️ SystemdTimer

Makes sure the system is active whenever a systemd timer (https://www.freedesktop.org/wiki/Software/systemd/) is scheduled to run next. keeping things in sync, main character energy only 👑

Options

  • match — a regular expression selecting the systemd timers (https://www.freedesktop.org/wiki/Software/systemd/) to check. This expression matches against the names of the timer units, for instance logrotate.timer. Wanna know which timers exist? Run systemctl list-timers and go look 🔍

🔎 XPath

A generic check that queries a configured URL and expects the reply to contain XML data. The returned XML document gets parsed with a configured XPath expression (https://www.w3.org/TR/xpath/) that has to return timestamps UTC — as strings, not elements, okay? Those get interpreted as the wake up times. And if multiple entries exist, the soonest one is used. first come, first woken 🥇

Options

  • url — the URL to query for the XML reply 📡
  • xpath — the XPath query to execute. Must always return number strings or nothing 💫
  • timeout — timeout for executed requests, in seconds. Default: 5 ⏱️
  • username — optional user name for authenticating at a server requiring authentication. If used, also a password must be provided. duo, not solo 💞
  • password — optional password for authenticating at a server requiring authentication. If used, also a user name must be provided. (same deal, both or neither) 🤝

📐 XPathDelta

Comparable to XPath, except this one expects the returned results to represent the wake up time as a delta to the current time, in a configurable unit. spicy twist 🌶️

This check can, for instance, be used for tvheadend (https://tvheadend.org/) with the following expression:

//recording/next/text()

Options

  • url — the URL to query for the XML reply 📡
  • username — optional user name for authenticating at a server requiring authentication. If used, also a password must be provided. 💞
  • password — optional password for authenticating at a server requiring authentication. If used, also a user name must be provided. 🤝
  • xpath — the XPath query to execute. Must always return number strings or nothing. no pressure, but like, all the pressure 💅
  • timeout — timeout for executed requests, in seconds. Default: 5 ⏱️
  • unit — a string indicating which unit the delta is specified in. Valid options are: microseconds, milliseconds, seconds, minutes, hours, days, weeks. Default: minutes 🕰️

👑 Author

Johannes Wienke 💜

2017, Johannes Wienke 📝

and that's a wrap on the whole page, bestie!! 🎀🦋 this version is 10.1, dated May 09, 2026, and yeah it lives at AUTOSUSPEND.CONF(5) — go forth and suspend responsibly, you absolute icon 💖✨🌸

📦 where this page comes from