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