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