auto-suspend: A simple but handy system monitor
=================================================
auto-suspend is a small bash script that performs a series of configurable tests
to determine whether the system is still in use, or is doing something useful or
just not and can be therefore suspended. The intended operating place is a small
home server.

Even though auto-suspend works most of the time alone without user interaction,
it can tell a little about itself:

    $ auto-suspend help
    Usage:
        auto-suspend [COMMAND [ARG]]

    COMMANDs are:
        on [ID]             Enable auto suspend by rm 'rm $OffDir/ID'
        off [ID]            Disable auto suspend by 'touch $OffDir/ID'
        daemon              Start in daemon mode
        clerk               Start in clerk mode
        info                Show some config and status information
        help,-?,-h,--help   You read it now

    Hints:
        Without any command we start in the configured RunMode, see 'info'
        When [ID] at on/off is not given, is 'general' as default used
        on/off don't run any checks, they do as said and exit


Requirements
==============
Nothing really special that not every *nix box should have, but:
- bash >= 4,  due to use of mapfile and no POSIX coding style.
- ping
- pgrep
- grep
- find
- smbstatus (optionally)
- systemd (optionally)

Although systemd is optionally, it is used as default. If you don't use systemd,
then you will know how to setup your box to accomplish an equivalent result.


Installation
==============
Packages
----------
Arch users will find auto-suspend in AUR. This package will install all below
mentioned files but requires manual setup as described below. So read careful
and make your decisions which service file to enable or not.


From Source
-------------
There is no install script provided, so you need to copy the files tedious
by hand, e.g:

    # install -Dm755 auto-suspend /usr/bin/
    # install -Dm644 auto-suspend.conf /etc/

So far so simple, but now you have to make the first hard decision, in which
mode you want to run this nice script, "daemon" or "clerk". It may wise to read
and modify the fresh installed config file NOW! There is some info stuff there
that could help to continue here. This file must not only be edited to adapt it
to your needs, but also to enable auto-suspend in the first place.


Daemon Mode Setup
-------------------
In daemon mode, you probably want to ensure that this script is started after
boot, e.g. by using the supplied systemd service file:

    # install -Dm644 auto-suspend-daemon.service /etc/systemd/system/
    # systemctl enable --now auto-suspend-daemon.service


Clerk Mode Setup
------------------
In classic clerk mode you need to ensure that this script is called as often as
you like, e.g. by cron or systemd-timer. There are two simple files provided,
which will run auto-suspend every 5min. Modify the timer file or send a patch
which will improve these files to accept a time-argument when enabled.

    # install -Dm644 auto-suspend-clerk.service /etc/systemd/system/
    # install -Dm644 auto-suspend-clerk.timer /etc/systemd/system/

As usual you need to enable and start the services.

    # systemctl enable --now auto-suspend-clerk.timer

To check the success

    $ systemctl list-timers

If you prefer to use cron instead of systemd-timer, you can proceed as follows
to add a job that runs every 5 minutes.

    $ echo "*/5 * * * * root /usr/bin/auto-suspend" | sudo tee -a /etc/crontab


Miscellaneous - Tips/Notes/Ideas
==================================
- The configFile is mandatory! If not found we exit with an error immediately!
  Even worse it is hard coded expected at /etc/auto-suspend.conf. But you can
  force auto-suspend to use a different config file like this:

    $ configFile="/some/path/file" auto-suspend

  This was only added for hacking/testing. Would be nicer we support XDG stuff
- I'm not sure if the clerk mode makes sense at all, I was close to removing it,
  but the original authors may have a reason why they want it this way
- Maybe we should remove the RunMode config setting, which was only my first
  approach. But then I add the commands which looks somehow more sensible
- After a first positive check could be a script called, what then e.g. send a
  notification that the system will suspend after the next cycle
- The info command could be split into info/status, where status only do the
  checks.


License
=========

    SPDX-License-Identifier: GPL-3.0-or-later

    auto-suspend: A simple but handy system monitor
    Copyright (C) 2024 loh.tar@googlemail.com

    This auto-suspend is based on
    https://bbs.archlinux.org/viewtopic.php?pid=1225757#p1225757
    https://wiki.ubuntuusers.de/Archiv/Skripte/AutoSuspend/


Thanks To
===========
- The unknown original authors and Arch user teateawhy, where I started from
- stackoverflow.com, stackexchange.com for their great knowledge base
- dict.cc and deepl.com without which my English would be even worse
- github.com for kindly hosting
- Mom&Dad and archlinux.org


Release History
=================
Last version is 0.8.1 - Mar, 2024
-----------------------------------
- Add AUR hint
- Change install path from sbin to bin
- Improve documentation
- Some minor changes, see commit log for details


Very first version was 0.8 - Feb, 2024
----------------------------------------
- General review of the code, using more shell like techniques
- Move more code into functions
- Rename variables to CamelCase, change indention
- Improve documentation, at least I think so, thanks DeepL at this point!
- Add a so called daemon mode, commands clerk/daemon
- Add LogLevel setting, well poor implemented but anyway a little improvement
- Disabled using of logger, see comment in the code
- Add IgnoreLoginCount setting, at least useful while set up auto-suspend to
  watch proper working
- Add a check to ensure there is only one instance running
- Add the commands on/off/help/info
- Extended the concept with the OffFile to OffDir, so that more then one process
  can block suspend without getting in each other's way
- Add SuspendCommand setting to be flexible on how to suspend the system
- Rename the script slightly, just to indicate it's not the same
- Add a license and my copyright, just to have it sane and complete