commit - 957fedb0da7ca3872cdb8fedf768138bfc0c8624
commit + e94c92331759f7f3132038408d4716ea3bb69df0
blob - e34c305fa2a210dc0b156a2d9670c28c929e7591
blob + 7cb5bd676da1676586d61cb7e7a9972d03cb4d21
--- vdcron.8
+++ vdcron.8
.Op Fl f Ar file
.Sh DESCRIPTION
.Nm
-is first of all a cron.
+is is first of all a cron.
.Pp
-Like any cron, you can use it to run commands at a specific moment: day, hour, minute. But you can also use it to run a command every Monday, or every 10 days, every odd days, every hour, every 5 hour, each Monday at 10AM, every months, every 2 months, … Nothing different than usual cron.
+Like many cron, you can use it to run commands at a specific moment: day, hour, minute. But you can also use it to run a command every Monday, or every 10 days, every odd days, every hour, every 5 hour, each Monday at 10AM, every months, every 2 months, … Nothing different than usual cron.
.Pp
What makes vdcron special? :
.Bl -bullet -compact
.Nm
is not planned to run permanently as a daemon, but an external program will trigger
.Nm .
-It can be your normal cron, it can be your .profile script, it can be your .login script. In my case
+It can be you normal cron, it can be your .profile script, it can be your .login script. In my case
.Nm
is triggered by the resume process of
-.Xr apmd 8 .
+.Xr apmd 8 .
Thus each time I open the lid of my laptop,
.Nm
-is triggered and executes commands that he must run. You can find details here under.
+is triggered and execute commands that he must run.
.It
Since
.Nm
-is not a daemon, the config file and the schedule are a little bit different from what we are used to use in cron programs. Please look at
-.Xr vdcron.conf 8 for details.
+is not a daemon, the config file and the schedule are a little bit different from what we are used to use in cron programs.
.El
.Pp
-The
-.Nm
-options are:
+The options are as follows:
.Bl -tag -width "-s value"
.It Fl h
Help. Display the possible parameters
.Sh How trigger vdcron ?
I remind that
.Nm
-is not a daemon. You have to regularly execute it.
+is not a daemon. You have to regurely execute it.
.Pp
For laptops, I think that the ideal is to trigger the execution of vdcron at each lid's open.
On
rcctl start apmd
.Ed
.Pp
-But others options to trigger
+But other option to trigger
.Nm
are possible.
Maybe you will prefer to trigger vdcron at each reboot. In such case, on
-.Ox ,
-just trigger
+.Ox
+, just trigger
.Nm
in your /etc/rc.local or in your normal
.Xr cron 8
For specific cases, you could imagine to trigger
.Nm
from your .login script of from your .profile script.
-Why not putting triggering vdcron from your cron every hour?
+Why not putting triggering vdcron from your cron every hour ?
.Pp
-It’s really up to you to decide when, how often, ... you want to trigger
+It’s really up to you to decide when, how often, ... you want to trigger
.Nm .
The ideal solution will depend on what you want to execute with
.Nm
and with which frequency (very days, every hours, minutes, ...)
.Sh FILES
-For root user, the config file and the log file are in different places than for normal users.
.Bl -tag -width "~/.vdcron/vdcron.conf" -compact
.It Pa /etc/vdcron.conf
The config file for the root user
.Xr cron 8
.Sh HISTORY
.Nm
-has been created in June 2018 on
+has been created in June 2018
.Ox 6.3 .
-.Pp
-Since version 0.6 is runs on debian Jessie too. So should run successfully on all linux machines.
.Sh AUTHOR
.Nm
was written by
.An Vincent Delft Aq Mt vincent.delft@gmail.com .
.Sh CAVEATS
.Nm
-has been developed on
+has been developped on
.Ox .
blob - df47808772304406ff93b736567d88c779349abd
blob + b0112e4c188a801bdec67ffff9d88761c44eb7de
--- vdcron.conf.8
+++ vdcron.conf.8
.\"
-.\" Copyright (c) 2018 Vincent Delft <vincent.delft@gmail.com>
+.\" Copyright (c) 2018 Vincent Delft <vinent.delft@gmail.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.Nm vdcron.conf
.Nd the config file of
.Xr vdcron 8
+.Nm vdcron.conf
.Sh DESCRIPTION
.Nm
-is where we define tasks to execute and their schedules.
+is where we define the task to execute and their schedules.
.Pp
-.Xr vdcron 8
-relies on one config file. This config file is /etc/vdcron.conf if you run vdcron as root, or it is ~/.vdcron/vdcron.conf for each other users.
+.Xr Vdcron 8
+relies on 1 config file. This config file is /etc/vdcron.conf if you run it with a root account, or it will be ~/.vdcron/vdcron.conf for each other users.
.Pp
-The basic concept of the conf file is that, like in a queue, each line represents a command that we have to trigger if the schedule timing is compliant with the current date and time at which
+The basic concept of the conf file is that, like in a queue, each line represent a command that we have to trigger if the schedule timing is compliant with the current date and time at which
.Xr vdcron 8
-is executed. For example, if you ask vdcron to run a command on Monday, vdcron will not run it until it's Monday. Once successfully executed the command will be removed from the config file. This is why I’m talking about the queuing principle. This aspect is not what we are used to have in “normal”
+is executed. For example, if you ask vdcron to run a command on Monday, vdcron will not run it until we are a Monday. Once successfully executed the command will be removed from the config file. This is why I’m talking about the queuing principle. This aspect is not what we are used to have in “normal”
.Xr cron 8
-systems. If you want to keep relevant information in the
-.Nm ,
-feel free to use comments. For details check here under.
+systems.
.Pp
-If I take a specific case, you can ask vdcron to run a command at Noon on May 1st. In such case, vdcron will execute it if we are between 12:00:00 and 12:00:59. Before it’s too soon, after it’s too late.
+If I take a specific case, you can ask vdcron to run a command at Noon on May 1st. In such case, vdcron will execute it if we are after 12:00:00 on that day. Before it’s too soon.
.Pp
-Since vdcron is foresee to run on non-permanent machines, such concept, with a very strict timing, (with hour and minute) is possible, but is not the usual case of vdcron. We prefer situations where we specify the day. We expect to have the command executed on that day, and we are less demanding for the timing. Or you can ask vdcron to execute your task after a precise timing. We will see here bellow how to manage very strict timing.
+Since vdcron is foresee to run on non-permanent machines, we cannot be very strict on hour and minutes at which the command will be executed. But if you add "+" in front of the data, it will be exected once the timing has been reached. Moreover vdcron will keep in his queue processes which has been failed. Those are major differentiator with usual cron.
.Pp
-The command part can be a command with his parameters, but it can also be a list of commands (split by “;”) or a command that you want to launch in background (add “&” at the end). In the later case, the return code of the command will not be used, vdcron will estimate that the job is successful. Thus, background commands will never be restarted if they fail.
+The command part can be a command with his parameters, but it can also be a list of commands (split by “;”) or a command that you want to launch in background (add “&” at the end). In the later case, the return code of the command will not be used, vdcron will estimate that the job is successful. Thus, background commands will never be restarted if they fails.
.Ss The config file must respect some conventions:
-.Pp
+
.Ic /date/ /command and parameters/
the 2 elements must be separated by one space
.Pp
-The date component can have the following formats:
+Date can have the following formats:
.Bl -tag -width Ds
.It Ic [+]YYYYmmdd[/d]
or
-.Ic [+]HHMM[/d]
-or
.Ic [+]YYYYmmddHHMM[/d]
-In case you put the "+" sign in front this means that the command will run even we are after this specific date.
+In case you put the "+" sign in front this means that the command will run even we are after this specific date and time
In case you append with a "/" and digit(s), the command will be re-scheduled automatically for later.
-The digits represent the number of time units you want to add to the current moment.
-This unit is always the last one used by the timing associated. Thus for a schedule with HHMM and YYYYmmddHHMM, the digits you have specified will add minutes.
+The digits represent the number of time unit you want to add to the current moment.
+This unit is always the last one used by the timing associated. Thus for a schedule with YYYYmmddHHMM, the digits you have specified will add minutes.
For YYYYmmdd, you will add days.
-For example, with a date like this 20180702/7, on 2nd of July the command will be rescheduled for July, the 9rd.
-If I put a date format like 1245/15, vdcron will reschedule it for 1300 (which is 13h00).
-Note that those rescheduling will occurs if the return code of the command is zero (cfr here bellow).
.It Ic Weekday
A locale's full weekday name with optionally re-schedule digits. For example: Monday/7.
As explained above, in this case, the rescheduling unit for will be in days.
.It Ic Month
A locale's full month name with optionally re-schedule digits. For example: April/1.
As explained above, in this case, the rescheduling unit will be in months
-.It Ic Always
+.It Ic Always.
With this keyword your command will always been executed when you trigger vdcron
.El
.Pp
-The command part can accept the following format:
-.Bl -tag -width Ds
-.It normal command
-You can ask vdcron to trigger any specific command. The results of the command (and some other info) are stored in the log file: /var/log/vdcron.log for root and ~/.vdcron/vdcron.log for other users.
-If the return code of the command is not zero "0", the line will not be removed from the config file. In other words, vdcron will re-check the date conditions, if they are successful vdcron will re-execute it. For example, this is useful for script requiring network connections, which you could not always have (surely with laptops).
-.It group of commands
-You can also group several commands by separating them by a semi-column ";". The return code that vdcrom will take into account will be the one of the last command. So if you do not want to take into account the return code of one specific command, just append it with "; true". The command "true" is a specif unix command which always return a return code of "0".
-At contrary if you always finalize your command by the command “false”, the command will always remain in the vdcron.conf file. This is like with the “Always” keyword.
-.It background command
-vdcron triggers all command that are compatible with the date format one by one. If you prefer to put some of those commands in background, just append the "&" character at the end of your command. In such case the return code will always be zero.
-.It command can be preceded with Ic "-q ".
-In such case there will be no logging at all.
-.El
-.Pp
-Environment parameters:
-.Bl -tag -width Ds
-.It
+
+/command/ can be preceded with "-q ", we are in quiet mode. In such case there will be no logging at all. Without this parameter the results of the command (and some other info) are stored in the log file: ~/.vdcron/vdcron.log for standard users and /var/log/vdcron.log for root.
+ If the exit code is not zero "0", and of you have the "+" in front of the date, the line will not be removed from the config file. In other words, vdcron will retry until successful execution. This is useful for script requiring network connections, which you could not always have (surely with laptops).
+ As consequence if you always finalize your command by the command “false”, the command will always remain in the vdcron.conf file. This is like with the “Always” keyword.
+
You can also define some environment variable by respecting the following structure:
-/var/=/value/.
+/var/=/value/
+
+“var” should be alpha characters. “value” can be alpha, numeric or alphanumeric.
Such settings is exactly like you do in your usual shell scripts. Please do not put spaces before or after the sign “=” or before the “var”.
-.It /var/
-“var” should be alpha characters.
-.It /value/
- can be alpha, numeric or alphanumeric.
-.El
-.Pp
+
All lines, in the config file, which do not respect those formats will be treated as a comment. By looking at the log files, you can identified them easily.
Thus, since, commands been successfully executed will be removed from the config file, adding some comments or keeping a copy of your line preceded by a “#” character will allow you to easily remember it.
-.Sh CONFIG FILE examples
-.Pp
-Let's start with a simple echo command:
-.Bd -literal -offset indent
-20180429 echo "Last weekend of April"
-.Ed
-.Pp
+## Config file examples
+
+ 20180429 echo "Last weekend of April"
+
As explained, the 1st word is the schedule requirement, all the rest is your command.
In this case, we ask to execute on 2018, April the 29th the command that will echo the funny text “Last weekend of April”. All of this will be present in the log file.
-.Bd -literal -offset indent
-+20180429/1 sh /etc/daily
-.Ed
-.Pp
+
+
+ +20180429/1 sh /etc/daily
+
In this case we ask vdcron to execute on 2018 April 29th, or after, the /etc/daily script. Moreover, if the return code of “/etc/daily” is zero (successful), we ask vdcron to reschedule it 1 day after.
-If the command “/etc/daily” return a non-zero return code, the line will remain in the config file untouched. So, if you re-execute vdcron, it will re-trigger this line too since the date constraints is still valid.
-.Bd -literal -offset indent
-+20180429/1 sh /etc/daily; true
-.Ed
-.Pp
-With this line in the config file, we enforce the fact that command will run once, and only once, per day because the return code will always be zero. As said, above, if the scheduled date is in the past (in case the machine was down more than 1 day), the command will be triggered anyhow thanks to the "+" sign.
-.Bd -literal -offset indent
-Sunday sh /etc/weekly_once
-+20180429/7 sh /etc/weekly
-Sunday/7 sh /etc/weekly
-.Ed
-.Pp
+If the command “/etc/daily” return a non-zero return code, the line will remain in the config file untouched.
+
+ +20180429/1 sh /etc/daily; true
+
+With this line in the config file, we enforce the fact that command will run once, and only once, per day because the return code will always be zero. As said, above, if the scheduled date is in the past (in case the machine was down more than 1 day), the command will be triggered anyhow.
+
+ +201804291215/60 sh /etc/my_hourly_tasks
+
+With this line in the config file, we enforce the fact that command will run every hours (repetition of 60 minutes) at hour + 15 minutes. As said above, thanks to the "+", if the scheduled date is in the past (in case the machine was down more than 1 day), the command will be triggered anyhow. If the task is succesfull, it will be triggered for the next hour + 15 minutes.
+
+ Sunday sh /etc/weekly_once
+ +20180429/7 sh /etc/weekly
+ Sunday/7 sh /etc/weekly
+
Those are 3 “weekly” command. Except that the 1st one will run only once; the 2 others will be rescheduled.
The 2 others will run every 7 days. Since Sunday + 7 days is also Sunday, vdcron will add a “_” at the beginning of the word. If we are Sunday, this sign allow vdcron differentiate a task to execute from a task to no more execute. Vdcron will remove this special character when needed. You don’t have to remove it your self.
The difference between the last 2 entries, is that the 2nd one will be executed even if we trigger vdcron after the specified date. With the 3rd line, if you never trigger vdcron on Sunday, you will have to wait next Sunday for an execution.
-.Bd -literal -offset indent
-Always echo "heartbeat"
-+20180429/1 echo “heartbeat”;false
-.Ed
-.Pp
+
+ Always echo "heartbeat"
+ +20180429/1 echo “heartbeat”;false
+
The “Always” keyword informs vdcron to run the command every time vdcron is started.
The 2nd line has the same effect. Indeed, each time the command will return a non zero return code, so vdcron will keep the command on the config file and will trigger it at each run.
-.Bd -literal -offset indent
-April sh /etc/monthly_once
-+20180401/31 /etc/monthly
-April/1 /etc/monthly
-.Ed
-.Pp
+
+ April sh /etc/monthly_once
+ +20180401/31 /etc/monthly
+ April/1 /etc/monthly
+
Those are 3 methods to run a monthly command. The 1st line will be execute only once, because not rescheduled. The 2 others will be rescheduled just after correct execution of the command. If you are not sure and want to avoid that such monthly script will be triggered each time vdcron run, you can add “; true” at the end of each line.
On the 2nd line vdcron will re-schedule the command 31 days after 1st of April 2018. So, this will be rescheduled for 2nd of May. Then, 2nd of June 2018, then 3rd of July, … On the opposite, the 3rd line will always be reschedule for the next month, without any specification for the day.
Like for week day’s name, vdcron will add a “_” sign at the beginning to mark script already successfully executed.
-.Sh REAL CONFIG file
-.Pp
+## a Real config file
+
I remind that in my implementation, I trigger vdcron via /etc/apm/resume (at each lid open)
My personal config file for root is the following:
-.Bd -literal -offset indent
-$ doas more /etc/vdcron.conf
-+20180509/1 sh /etc/daily &
-Sunday/7 sh /etc/weekly &
-Always su - vi -c "/usr/local/bin/vdcron -s3 "
-Always pkg_info -m > /root/pkg_installed.txt
-Always /root/my_laptop_backup.sh
-.Ed
-.Pp
-With this config, I run my /etc/daily once per day in background. I run the weekly script every Sunday. If I do not open my machine on a Sunday, I accept to skip it until next Sunday. I always run my Network Manager script (details here http://www.vincentdelft.be/post/post_20180411). And finally, I always trigger vdcron for my own user: vi. The "-s3" means that I force a sleep to 3 seconds.
+ $ doas more /etc/vdcron.conf
+ +20180509/1 sh /etc/daily &
+ 20180512/7 sh /etc/weekly &
+ Always /usr/local/bin/nmctl -r -w 5 -R 5 >> /tmp/nmctl.log
+ Always su - vi -c "/usr/local/bin/vdcron -s3 "
+With this config, I run my /etc/daily once per day in background. I run the weekly script every Saturday (or later). If I do not open my machine on a Saturday, I accept to run it on Sunday or Monday or … I always run my Network Manager script (details [here](http://www.vincentdelft.be/post/post_20180411) ). And I always trigger vdcron for my own user: vi.
+
In my vi’s home directory, I have the following vdcron.conf file
-.Bd -literal -offset indent
+
$ more ~/.vdcron/vdcron.conf
+20180509/1 openboxmenuCreate &
+20180511/7 sh ~/bin/sync_working_files.sh
-.Ed
-.Pp
-In my case, once per day I run a python script I’ve made to recreate my openbox’s menus.
-On a weekly basis (cannot be always the same day), I sync my local working files to my NAS. If I’m not connected to my NAS vdcron will keep it in the config file. Moreover, in this case, I accept to run it after the Friday (October 11th) because sign “+”.
+In my case, I run once per day a python script I’ve made to recreate my openbox’s menus.
+On a weekly basis (ideally on Friday), I sync my local files to my NAS. If I’m not connected to my NAS vdcron will keep it in the config file. Moreover, in this case, I accept to run it after the Friday or later (because sign “+”)
+
.Sh FILES
.Bl -tag -width "~/.vdcron/vdcron.conf" -compact
.It Pa /etc/vdcron.conf
.An Vincent Delft Aq Mt vincent.delft@gmail.com .
.Sh CAVEATS
.Nm
-has been developed on
+has been developped on
.Ox .
-.Pp
-Since version 0.6 is runs on debian Jessie too. So should run successfully on all linux machines.
