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