doc/call.texi

   1 @node Call
   2 @unnumbered Call configuration
   3
   4 Call is a rule when and how node can be called.
   5
   6 Example list of call structures:
   7
   8 @verbatim
   9 calls:
  10   -
  11     cron: "*/1 * * * MON-FRI"
  12     onlinedeadline: 3600
  13     nice: PRIORITY+10
  14   -
  15     cron: "30 * * * SAT,SUN"
  16     onlinedeadline: 1800
  17     maxonlinetime: 1750
  18     nice: NORMAL
  19     rxrate: 10
  20     txrate: 20
  21   -
  22     cron: "0 * * * SAT,SUN"
  23     xx: rx
  24     addr: lan
  25 @end verbatim
  26
  27 tells that on work days of the week call that node every minute,
  28 disconnect after an hour of inactivity and process only relatively high
  29 priority packets (presumably mail ones). So we connect and hold
  30 connection for very long time to pass only emails. On weekends call that
  31 node only each half-hour for processing high-priority packets. Also only
  32 on weekends try to connect to that node every hour only using LAN
  33 address and only receiving any (any priority) packets (assume that low
  34 priority huge file transmission are done additionally via offline
  35 connections).
  36
  37 It contains the following fields (only @emph{cron} is required):
  38
  39 @table @emph
  40
  41 @item cron
  42 This is copy-pasted documentation from
  43 @code{github.com/gorhill/cronexpr} library used there.
  44
  45 @multitable @columnfractions .2 .1 .2 .5
  46 @headitem Field name @tab Mandatory? @tab Allowed values @tab Allowed special characters
  47
  48 @item Seconds @tab No @tab 0-59 @tab @verb{|* / , -|}
  49 @item Minutes @tab Yes @tab 0-59 @tab @verb{|* / , -|}
  50 @item Hours @tab Yes @tab 0-23 @tab @verb{|* / , -|}
  51 @item Day of month @tab Yes @tab 1-31 @tab @verb{|* / , - L W|}
  52 @item Month @tab Yes @tab 1-12 or JAN-DEC @tab @verb{|* / , -|}
  53 @item Day of week @tab Yes @tab 0-6 or SUN-SAT @tab @verb{|* / , - L #|}
  54 @item Year @tab No @tab 1970–2099 @tab @verb{|* / , -|}
  55
  56 @end multitable
  57
  58 @table @asis
  59
  60 @item Asterisk (@verb{|*|})
  61
  62 The asterisk indicates that the cron expression matches for all values
  63 of the field. E.g., using an asterisk in the 4th field (month) indicates
  64 every month.
  65
  66 @item Slash (@verb{|/|})
  67
  68 Slashes describe increments of ranges. For example @verb{|3-59/15|} in
  69 the minute field indicate the third minute of the hour and every 15
  70 minutes thereafter. The form @verb{|*/...|} is equivalent to the form
  71 "first-last/...", that is, an increment over the largest possible range
  72 of the field.
  73
  74 @item Comma (@verb{|,|})
  75
  76 Commas are used to separate items of a list. For example, using
  77 @verb{|MON,WED,FRI|} in the 5th field (day of week) means Mondays,
  78 Wednesdays and Fridays.
  79
  80 @item Hyphen (@verb{|-|})
  81
  82 Hyphens define ranges. For example, 2000-2010 indicates every year
  83 between 2000 and 2010 AD, inclusive.
  84
  85 @item L
  86
  87 @verb{|L|} stands for "last". When used in the day-of-week field, it
  88 allows you to specify constructs such as "the last Friday" (@verb{|5L|})
  89 of a given month. In the day-of-month field, it specifies the last day
  90 of the month.
  91
  92 @item W
  93
  94 The @verb{|W|} character is allowed for the day-of-month field. This
  95 character is used to specify the business day (Monday-Friday) nearest
  96 the given day. As an example, if you were to specify @verb{|15W|} as the
  97 value for the day-of-month field, the meaning is: "the nearest business
  98 day to the 15th of the month."
  99
 100 So, if the 15th is a Saturday, the trigger fires on Friday the 14th. If
 101 the 15th is a Sunday, the trigger fires on Monday the 16th. If the 15th
 102 is a Tuesday, then it fires on Tuesday the 15th. However if you specify
 103 @verb{|1W|} as the value for day-of-month, and the 1st is a Saturday,
 104 the trigger fires on Monday the 3rd, as it does not 'jump' over the
 105 boundary of a month's days.
 106
 107 The @verb{|W|} character can be specified only when the day-of-month is
 108 a single day, not a range or list of days.
 109
 110 The @verb{|W|} character can also be combined with @verb{|L|}, i.e.
 111 @verb{|LW|} to mean "the last business day of the month."
 112
 113 @item Hash (@verb{|#|})
 114
 115 @verb{|#|} is allowed for the day-of-week field, and must be followed by
 116 a number between one and five. It allows you to specify constructs such
 117 as "the second Friday" of a given month.
 118
 119 @end table
 120
 121 Predefined cron expressions:
 122
 123 @multitable @columnfractions .1 .75 .15
 124 @headitem Entry @tab Description @tab Equivalent to
 125 @item @verb{|@annually|} @tab
 126     Run once a year at midnight in the morning of January 1 @tab
 127     @verb{|0 0 0 1 1 * *|}
 128 @item @verb{|@yearly|} @tab
 129     Run once a year at midnight in the morning of January 1 @tab
 130     @verb{|0 0 0 1 1 * *|}
 131 @item @verb{|@monthly|} @tab
 132     Run once a month at midnight in the morning of the first of the month @tab
 133     @verb{|0 0 0 1 * * *|}
 134 @item @verb{|@weekly|} @tab
 135     Run once a week at midnight in the morning of Sunday @tab
 136     @verb{|0 0 0 * * 0 *|}
 137 @item @verb{|@daily|} @tab
 138     Run once a day at midnight @tab
 139     @verb{|0 0 0 * * * *|}
 140 @item @verb{|@hourly|} @tab
 141     Run once an hour at the beginning of the hour @tab
 142     @verb{|0 0 * * * * *|}
 143 @end multitable
 144
 145 @itemize
 146 @item
 147 If only six fields are present, a @verb{|0|} second field is prepended,
 148 that is, @verb{|* * * * * 2013|} internally become
 149 @verb{|0 * * * * * 2013|}.
 150 @item
 151 If only five fields are present, a @verb{|0|} second field is prepended
 152 and a wildcard year field is appended, that is, @verb{|* * * * Mon|}
 153 internally become @verb{|0 * * * * Mon *|}.
 154 @item
 155 Domain for day-of-week field is [0-7] instead of [0-6], 7 being Sunday
 156 (like 0). This to comply with @url{https://linux.die.net/man/5/crontab}.
 157 @end itemize
 158
 159 @item nice
 160 Optional. Use that @ref{Niceness, niceness} during the call (255 is used
 161 otherwise).
 162
 163 @item xx
 164 Optional. Either @verb{|rx|} or @verb{|tx|}. Tells only to either to
 165 receive or to transmit data during that call.
 166
 167 @item addr
 168 Optional. Call only that address, instead of trying all from
 169 @ref{CfgAddrs, @emph{addrs}} configuration option. It can be either key
 170 from @emph{addrs} dictionary, or an ordinary @option{addr:port}.
 171
 172 @item rxrate/txrate
 173 Optional. Override @ref{CfgXxRate, @emph{rxrate/txrate}} configuration
 174 option when calling.
 175
 176 @item onlinedeadline
 177 Optional. Override @ref{CfgOnlineDeadline, @emph{onlinedeadline}}
 178 configuration option when calling.
 179
 180 @item maxonlinetime
 181 Optional. Override @ref{CfgMaxOnlineTime, @emph{maxonlinetime}}
 182 configuration option when calling.
 183
 184 @end table