nix-git/examples/systemd-timer-example.nix

{ config, pkgs, ... }:

# TODO Note: One can specify ExecStart and ExecStop. Maybe to pause some script during shutdown/suspend? This would be nice for backups. Just finish the current snapshot then pause.
#
# ExecStop=
#   Commands to execute to stop the service started via ExecStart=.
#   The command that asks the service to stop should wait for it to do so!
#   After the commands configured in this option are run, it is implied that the service is stopped, and any processes remaining for it are terminated.
#
#   If this option is not specified, the process is terminated when service stop is requested.

# TODO: https://unix.stackexchange.com/questions/619987/stop-systemd-service-before-suspend-start-again-after-resume

# Benefits of Systemd Timers over cron: https://wiki.archlinux.org/title/Systemd/Timers#Benefits
# Example: https://nixos.wiki/wiki/Nix_Cookbook#Creating_periodic_services
# Example: https://nixos.wiki/wiki/Systemd/Timers
{
  systemd.timers."hello-world" = {
    # description = "My Timer";
    wantedBy = [ "timers.target" ];
    # If the service stopped or restarted, then this timer is stopped or restarted as well.
    partOf = [ "hello-world.service" ];
    # https://man.archlinux.org/man/systemd.timer.5
    timerConfig = {
      # Either calendar time.
      # Or relative time. https://unix.stackexchange.com/a/294200/315162
      #
      OnCalendar = "monthly";
      Persistent = true; # Catch up on missed runs of the service when the system was powered down. This setting only has an effect on timers configured with OnCalendar=.
      #
      #OnBootSec = "0m";
      #OnUnitActiveSec = "30d";
      #OnUnitInactiveSec = "30d";

      # To optimize power consumption, make sure to set this value as high as possible and as low as necessary.
      AccuracySec = "2d";
      # This setting is useful to stretch dispatching of similarly configured timer events over a certain time interval, to prevent them from firing all at the same time, possibly resulting in resource congestion.
      RandomizedDelaySec = "2d";

      # Takes a boolean argument. If true, an elapsing timer will cause the system to resume from suspend, should it be suspended and if the system supports this. Note that this option will only make sure the system resumes on the appropriate times, it will not take care of suspending it again after any work that is to be done is finished.
      # Note that this functionality requires privileges and is thus generally only available in the system service manager.
      #WakeSystem = true;
    };
  };

  systemd.services."hello-world" = {
    # description = "My Oneshot Service";

    # TODO: Prevents suspend2ram or proper shutdown?
    # https://github.com/NixOS/nixpkgs/blob/e9b4b56e5a20ac322c0c01ccab7ec697ab076ea0/nixos/modules/tasks/filesystems/btrfs.nix#L128-L130
    #
    # If the specified units are started, then this unit is stopped and vice versa.
    conflicts = [ "shutdown.target" "sleep.target" ];
    # If the specified units are started at the same time as this unit, delay them until this unit has started.
    before = [ "shutdown.target" "sleep.target" ];

    # https://man.archlinux.org/man/systemd.service.5.en#OPTIONS
    #   More options e.g.: https://man.archlinux.org/man/systemd.exec.5.en#SCHEDULING
    #
    # Example: https://github.com/NixOS/nixpkgs/blob/e9b4b56e5a20ac322c0c01ccab7ec697ab076ea0/nixos/modules/tasks/filesystems/btrfs.nix#L132-L142
    serviceConfig = {
      Type = "oneshot";
      PrivateTmp = true;

      #User = "myuser";

      # Lowest scheduling priority.
      Nice = 19;
      # Takes one of the strings realtime, best-effort or idle.
      IOSchedulingClass = "idle";

      #ExecStart = "${pkgs.python3.withPackages my-python-packages}/bin/netcup-dns";
    };

    # Packages required for the script.
    #path = with pkgs; [
    #  openssh
    #  wget
    #  curl
    #];

    #environment = {
    #  MY_SERVICE_HOME = "/my/path/here";
    #  MY_SERVICE_MAX_CONNS = toString myVar;
    #};

    # Shell commands executed as the service's main process.
    script = ''
      set -eu
      ${pkgs.coreutils}/bin/echo "Hello World"
    '';
  };
}