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