10 releases (6 breaking)

Uses old Rust 2015

0.8.4 Mar 18, 2023
0.8.2 Feb 19, 2023
0.7.0 Jan 8, 2022
0.6.0 Nov 25, 2017

#111 in Unix APIs

47 downloads per month

GPL-3.0 license

54KB
1K SLoC

Circadian

Suspend-On-Idle Daemon for GNU/Linux Power Management

Circadian is a background daemon/service for triggering suspend/sleep/hibernate automatically when a computer is idle.

It is primarily for stationary devices with permanent power (i.e. desktops, servers, media centers).

Circadian uses a suite of 'idle heuristics' to determine when a system is idle. These include:

  • User activity in X11 (keyboard, mouse, full-screen playback)
  • User activity in terminals (typing in PTY/SSH session)
  • Open SSH connections
  • Open SMB/Samba connections
  • Open NFS connections
  • Active audio playback
  • CPU usage below specified threshold
  • Blacklisted processes

When all of its heuristics determine that your system has been idle for long enough, Circadian will execute a command. This is typically a simple power suspend, but it can be configured to any desired action.

Circadian can also schedule an automatic daily wakeup. Simply set a wake time in its configuration file and it will wake up once every day at that time (if not already awake). This allows an easy way to keep a machine updated and backed up, even if it is seldom used.

It can also execute a command when it detects that the system has woken up from sleep, regardless of why it woke up.

Circadian exists because modern Linux distros already support suspend-on-idle, but it is apparently a very buggy and unreliable domain. After you've followed your distro's advice of poking a handful of conf files, tweaking a few XML hierarchies, writing a few scripts, wafting the smoke of burning sage across your keyboard, suspending gem stones from your machine, and whatever else may be recommended... perhaps try Circadian.

Example use cases

  • Gaming rig with noisy fans? Auto-sleep when idle!
  • Storage/backup machine? Auto-wake, backup, and auto-sleep!
  • Seldom used server, but needs to be available? Wake-on-LAN, and auto-sleep when no SSH connections!
  • Wake up to your local music library? Auto-wake, play music, and auto-sleep!
  • Media center that you only use in evenings? Sleep all day, auto-wake when you get home!

Status

"Works for me". You try. You give feedback on GitHub, or to trevor@trevorbentley.com.

Installing

Debian x86-64

$ sudo dpkg -i circadian_0.6.0-1_amd64.deb

If desired, install tooling to detect network (netstat), X11 (xssstate andxprintidle), audio activity (pactl):

$ sudo apt-get install suckless-tools xprintidle net-tools pulseaudio-utils

Edit /etc/circadian.conf to configure. The default is to suspend with systemd after 2 hours of idle.

When you are happy with the config, continue:

$ sudo systemctl enable --now circadian

Arch Linux

  • Use your favorite AUR package manager
yay -S circadian

Consider installing the optional packages of xprintidle and xssstate for X11 based idle detection and net-tools for SSH detection. Both of this options are enabled by default.

Any other system with systemd

Install manually. It's easy.

$ git clone https://github.com/mrmekon/circadian.git
$ cd circadian
$ cargo build --release
$ sudo cp target/release/circadian /usr/local/bin/
$ sudo cp resources/circadian.conf.in /etc/circadian.conf
$ sudo cp resources/circadian.service /etc/systemd/system/
$ sudo systemctl enable circadian
$ sudo systemctl start circadian

Non-systemd systems

Follow systemd instructions, and port circadian.service to whatever format you want.

Dependencies

  • Might need to install
    • xssstate
    • xprintidle
    • netstat
    • pactl
    • rustc + cargo (if building locally)
  • Should already have
    • grep
    • awk
    • w
    • id
    • uptime
    • pgrep
    • cat
    • sh

Auto-wake requires kernel support for the real-time clock (RTC). You can check for the file /sys/class/rtc/rtc0/wakealarm. You probably have it.

Usage

  • Should run as root, ideally from systemd.
  • Config is in: /etc/circadian.conf (it is documented)
  • pkill -SIGUSR1 circadian will dump info to syslog. Use that to see if it's working, or find out why it isn't sleeping.

Dependencies

~8.5MB
~158K SLoC