Configures the autosuspend daemon.
The autosuspend configuration file uses INI syntax and
needs to be processable by the Python configparser module.
A simple configuration file could look like:
[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
The configuration file consists of a [general] section,
which specifies general processing options, and multiple sections of the
format [check.*] and [wakeup.*]. These sections describe the
activity and wake up checks to execute.
The [general] section contains options controlling the
overall behavior of the autosuspend daemon. These are:
- interval
- The time to wait after executing all checks in seconds.
- idle_time
- The required amount of time in seconds with no detected activity before
the host will be suspended. Default: 300 seconds
- min_sleep_time
- The minimal amount of time in seconds the system has to sleep for actually
triggering suspension. If a scheduled wake up results in an effective time
below this value, the system will not sleep. Default: 1200 seconds
- wakeup_delta
- Wake up the system this amount of seconds earlier than the time that was
determined for an event that requires the system to be up. This value adds
a safety margin for the time a the wake up effectively takes. Default: 30
seconds
- suspend_cmd
- The command to execute in case the host shall be suspended. This line can
contain additional command line arguments to the command to execute.
- wakeup_cmd
- The command to execute for scheduling a wake up of the system. The given
string is processed using Python's str.format() and a format
argument called timestamp encodes the UTC timestamp of the planned
wake up time (float). Additionally iso can be used to acquire the
timestamp in ISO 8601 format.
- notify_cmd_wakeup
- A command to execute before the system is going to suspend for the purpose
of notifying interested clients. This command is only called in case a
wake up is scheduled. The given string is processed using Python's
str.format() and a format argument called timestamp encodes
the UTC timestamp of the planned wake up time (float). Additionally
iso can be used to acquire the timestamp in ISO 8601 format. If
empty or not specified, no command will be called.
- notify_cmd_no_wakeup
- A command to execute before the system is going to suspend for the purpose
of notifying interested clients. This command is only called in case NO
wake up is scheduled. Hence, no string formatting options are available.
If empty or not specified, no command will be called.
- woke_up_file
- Location of a file that indicates to autosuspend that the computer
has suspended since the last time checks were executed. This file is
usually created by a systemd service. Thus, changing the location
also requires adapting the respective service. Refer to
systemd-integration for further details.
For each activity check to execute, a section with the name format
[check.*] needs to be created. Each check has a name and an executing
class which implements the behavior. The fraction of the section name
check. determines the name, and in case no class option is given
inside the section, also the class which implements the check. In case the
class option is specified, the name is completely user-defined and
the same check can even be instantiated multiple times with differing
names.
For each check, these generic options can be specified:
- class
- Name of the class implementing the check. If the name does not contain a
dot (.), this is assumed to be one of the checks provided by
autosuspend internally. Otherwise, this can be used to pull in third-party
checks. If this option is not specified, the section name must represent a
valid internal check class.
- enabled
- Needs to be true for a check to actually execute. false is
assumed if not specified.
Furthermore, each check might have custom options.
Wake up checks uses the same configuration logic as the previously
described activity checks. However, the configuration file sections start
with wakeup. instead of check..
The options of individual checks are outlined below.
The following checks for activity are currently implemented. Each
of the is described with its available configuration options and required
optional dependencies.
Checks an online iCalendar file for events that are
currently running. If so, this indicates activity and prevents suspending
the system. Thus, a calendar can be provided with times at which the system
should not go to sleep. If this calendar resides on an online service like a
groupware it might even be possible to invite the system.
- url
- The URL to query for the iCalendar file
- 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.
- requests
- icalendar
- dateutil
- tzlocal
Checks whether there is currently a client connected to a TCP
server at certain ports. Can be used to e.g. block suspending the system in
case SSH users are connected or a web server is used by clients.
- ports
- list of comma-separated port numbers
Executes an arbitrary command. In case this command returns 0, the
system is assumed to be active.
The command is executed as is using shell execution. Beware of
malicious commands in obtained configuration files.
- command
- The command to execute including all arguments
Checks whether an instance of Kodi is currently
playing.
- 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 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.
Checks whether there has been interaction with the Kodi user
interface recently. This prevents suspending the system in case someone is
currently browsing collections etc. This check is redundant to
XIdleTime on systems using an X server, but might be necessary in
case Kodi is used standalone. It does not replace the Kodi check, as
the idle time is not updated when media is playing.
- idle_time
- Marks the system active in case a user interaction has appeared within the
this amount of seconds 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 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.
Checks whether the system load 5 is below a certain
value.
- threshold
- a float for the maximum allowed load value, default: 2.5
Prevents suspending in case IdleHint for one of the running
sessions logind sessions is set to no. Support for setting
this hint currently varies greatly across display managers, screen lockers
etc. Thus, check exactly whether the hint is set on your system via
loginctl show-session.
- types
- A comma-separated list of sessions 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
Checks whether an instance of MPD is currently playing
music.
- 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
Checks whether more network bandwidth is currently being used than
specified. A set of specified interfaces is checked in this regard, each of
the individually, based on the average bandwidth on that interface. This
average is based on the global checking interval specified in the
configuration file via the interval option.
- 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
Checks whether one or more hosts answer to ICMP requests.
- hosts
- Comma-separated list of host names or IPs.
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.
- processes
- list of comma-separated process names to check for
Any active Samba connection will block suspend.
Checks whether a user currently logged in at the system matches
several criteria. All provided criteria must match to indicate activity on
the host.
All regular expressions are applied against the full string.
Capturing substrings needs to be explicitly enabled using wildcard
matching.
- 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, default: .*.
Checks whether all active local X displays have been idle for a
sufficiently long time. Determining 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 many other
configuration variants exist. Thus, multiple sources for active X serer
instances are implemented for this check, each of them having different
requirements and limitations. They can be changed using the provided
configuration option.
- 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 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 use 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.
- •
- dbus-python for the logind method
A generic check which queries a configured URL and expects the
reply to contain XML data. The returned XML document is checked against a
configured XPath expression and in case the expression matches, the
system is assumed to be active.
Some common applications and their respective configuration
are:
- tvheadend
- The required URL for tvheadend is (if running on the same
host):
http://127.0.0.1:9981/status.xml
In case you want to prevent suspending in case there are active
subscriptions or recordings, use the following XPath:
/currentload/subscriptions[number(.) > 0] | /currentload/recordings/recording/start
If you have a permantently running subscriber like Kodi,
increase the 0 to 1.
- Plex
- For Plex, use the following URL (if running on the same host):
http://127.0.0.1:32400/status/sessions/?X-Plex-Token={TOKEN}
Where acquiring the token is documented here.
If suspending should be prevented in case of any activity, this
simple XPath expression will suffice:
/MediaContainer[@size > 2]
- 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.
The following checks for wake up times are currently implemented.
Each of the checks is described with its available configuration options and
required optional dependencies.
Determines next wake up time from an iCalendar file. The
next event that starts after the current time is chosen as the next wake up
time.
Remember that updates to the calendar can only be reflected in
case the system currently running. Changes to the calendar made while the
system is sleeping will obviously not trigger an earlier wake up.
- url
- The URL to query for the XML reply.
- 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.
- xpath
- The XPath query to execute. Must always return number strings or
nothing.
- timeout
- Timeout for executed requests in seconds. Default: 5.
- requests
- icalendar
- dateutil
- tzlocal
Determines the wake up time by calling an external command The
command always has to succeed. If something is printed on stdout by the
command, this has to be the next wake up time in UTC seconds.
The command is executed as is using shell execution. Beware of
malicious commands in obtained configuration files.
- command
- The command to execute including all arguments
Determines the wake up time by reading a file from a configured
location. The file has to contains the planned wake up time as an int or
float in seconds UTC.
- path
- path of the file to read in case it is present
Always schedules a wake up at a specified delta from now on. Can
be used to let the system wake up every once in a while, for instance, to
refresh the calendar used in the Calendar check.
- unit
- A string indicating in which unit the delta is specified. Valid options
are: microseconds, milliseconds, seconds,
minutes, hours, days, weeks.
- value
- The value of the delta as an int.
A generic check which queries a configured URL and expects the
reply to contain XML data. The returned XML document is parsed using a
configured XPath expression that has to return timestamps UTC (as
strings, not elements). These are interpreted as the wake up times. In case
multiple entries exist, the soonest one is used.
- 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 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.
Comparable to XPath, but expects that the returned results
represent the wake up time as a delta to the current time in a configurable
unit.
This check can for instance be used for tvheadend with the
following expression:
- url
- The URL to query for the XML reply.
- 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.
- xpath
- The XPath query to execute. Must always return number strings or
nothing.
- timeout
- Timeout for executed requests in seconds. Default: 5.
- unit
- A string indicating in which unit the delta is specified. Valid options
are: microseconds, milliseconds, seconds,
minutes, hours, days, weeks. Default:
minutes