Provided by: autosuspend_3.0-1_all bug

NAME

       autosuspend.conf - autosuspend config file Documentation

SYNOPSIS

       /etc/autosuspend.conf

GENERAL CONFIGURATION

       Configures the autosuspend daemon.

   Configuration file
   Syntax
       The  autosuspend  configuration  file  uses  INI syntax and needs to be processable by the
       Python configparser <https://docs.python.org/3/library/configparser.html> 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.'
          lock_file = /var/lock/autosuspend.lock
          lock_timeout = 30

          [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.

   General configuration
       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   <https://www.freedesktop.org/wiki/Software/systemd/>   service.     Thus,
              changing  the  location  also  requires  adapting the respective service.  Refer to
              systemd-integration for further details.

       lock_file
              Location of a file that is used to synchronize the continuously running daemon  and
              the systemd callback.

       lock_timeout
              Timeout  in  seconds  used  when trying to acquire the lock.  This should be longer
              than the maximum run time of all configured checks.  In the worst cases, suspending
              the  system  is  delayed by this amount of time because presuspend hook has to wait
              before all checks have passed.

   Activity check configuration
       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 check configuration
       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..

       For options of individual checks, please refer to available-checks and available-wakeups.

AVAILABLE ACTIVITY CHECK

   Available activity checks
       The following checks for activity are currently implemented.  Each  of  the  is  described
       with its available configuration options and required optional dependencies.

   ActiveCalendarEvent
       Checks  an  online  iCalendar  <https://icalendar.readthedocs.io> 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.

   Options
       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.

   Requirementsrequests <https://pypi.python.org/pypi/requests>

       • icalendar <https://icalendar.readthedocs.io>

       • dateutil <https://dateutil.readthedocs.io>

       • tzlocal <https://pypi.org/project/tzlocal/>

   ActiveConnection
       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.

   Options
       ports  list of comma-separated port numbers

   Requirements
   ExternalCommand
       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.

   Options
       command
              The command to execute including all arguments

   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 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.

       suspend_while_paused
              Also suspend the system when media playback is paused instead  of  only  suspending
              when playback is stopped.  Default: false

   Requirementsrequests <https://pypi.python.org/pypi/requests>

   KodiIdleTime
       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.

   Options
       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.

   Requirementsrequests <https://pypi.python.org/pypi/requests>

   Load
       Checks whether the system load 5 <https://en.wikipedia.org/wiki/Load_(computing)> is below
       a certain value.

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

   Requirements
   LogindSessionsIdle
       Prevents  suspending  in  case  IdleHint  for  one  of   the   running   sessions   logind
       <https://www.freedesktop.org/wiki/Software/systemd/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.

   Options
       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

   Requirementsdbus-python <https://cgit.freedesktop.org/dbus/dbus-python/>

   Mpd
       Checks whether an instance of MPD <http://www.musicpd.org/> is currently playing music.

   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

   Requirementspython-mpd2 <https://pypi.python.org/pypi/python-mpd2>

   NetworkBandwidth
       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.

   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
   Ping
       Checks whether one or more hosts answer to ICMP requests.

   Options
       hosts  Comma-separated list of host names or IPs.

   Requirements
   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.

   Options
       processes
              list of comma-separated process names to check for

   Requirements
   Smb
       Any active Samba connection will block suspend.

   Options
       smbstatus
              executable needs to be present.

   Requirements
   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.

   Options
       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: .*.

   Requirements
   XIdleTime
       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.

   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 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.

   Requirementsdbus-python <https://cgit.freedesktop.org/dbus/dbus-python/> for the logind method

   XPath
       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
       <https://www.w3.org/TR/xpath/> expression and in case the expression matches,  the  system
       is assumed to be active.

       Some common applications and their respective configuration are:

       tvheadend <https://tvheadend.org/>
              The  required URL for tvheadend <https://tvheadend.org/> 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 <https://kodi.tv/>,
              increase the 0 to 1.

       Plex <https://www.plex.tv/>
              For Plex <https://www.plex.tv/>, 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
              <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
              <https://www.w3.org/TR/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.

   Requirementsrequests <https://pypi.python.org/pypi/requests>

       • lxml <http://lxml.de/>

AVAILABLE WAKEUP CHECK

   Available wake up checks
       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.

   Calendar
       Determines next wake up time from an  iCalendar  <https://icalendar.readthedocs.io>  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.

   Options
       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.

   Requirementsrequests <https://pypi.python.org/pypi/requests>

       • icalendar <https://icalendar.readthedocs.io>

       • dateutil <https://dateutil.readthedocs.io>

       • tzlocal <https://pypi.org/project/tzlocal/>

   Command
       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.

   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
       contains the planned wake up time as an int or 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.  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.

   Options
       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.

   XPath
       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
       <https://www.w3.org/TR/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.

   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 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.

   XPathDelta
       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 <https://tvheadend.org/> with the
       following expression:

          //recording/next/text()

   Options
       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

AUTHOR

       Johannes Wienke

COPYRIGHT

       2020, Johannes Wienke