1.\" $OpenBSD: ifstated.conf.5,v 1.16 2020/05/16 16:58:11 jmc Exp $ 2.\" 3.\" Copyright (c) 2005 Nikolay Sturm <sturm@openbsd.org> 4.\" Copyright (c) 2005 Marco Pfatschbacher <mpf@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: May 16 2020 $ 19.Dt IFSTATED.CONF 5 20.Os 21.Sh NAME 22.Nm ifstated.conf 23.Nd Interface State daemon configuration file 24.Sh DESCRIPTION 25The 26.Xr ifstated 8 27daemon runs commands in response to network state changes, which it 28determines by monitoring interface link state or running external tests. 29.Nm 30is the configuration file for this daemon. 31.Pp 32The 33.Nm 34config file is divided into the following main sections: 35.Bl -tag -width xxxx 36.It Sy Global Configuration 37Global settings for 38.Xr ifstated 8 . 39.It Sy Macros 40User-defined variables may be defined and used later, simplifying 41configuration. 42Macros must be defined before they are referenced in 43.Nm ifstated.conf . 44.It Sy State Definitions 45Definitions of states and transitions. 46.El 47.Sh GLOBAL CONFIGURATION 48.Bl -tag -width Ds 49.It Ic init-state Ar state 50Set the initial state to 51.Ar state 52instead of using the first state defined. 53.El 54.Sh MACROS 55Macros can be defined that will later be expanded in context. 56Macro names must start with a letter, digit, or underscore, 57and may contain any of those characters. 58Macros are not expanded inside quotes. 59.Pp 60Macro names may not be reserved words like, for example, 61.Ar state 62or 63.Ar run . 64Macros are referenced with a shell-like notation as 65.Em $macro . 66Macros are usually used to define tests for state transitions like interface 67link state or external tests. 68.Pp 69Currently an interface can have three different link states: 70.Pp 71.Bl -tag -width xxxxxxxx -compact 72.It Ar up 73The physical link of the interface is up. 74For 75.Xr carp 4 76interfaces this equals the master state. 77.It Ar down 78The physical link of the interface is down. 79For 80.Xr carp 4 81interfaces this equals the backup state. 82.It Ar unknown 83The physical link of the interface is unknown. 84This is because the interface driver does not provide information of the 85physical link state. 86For 87.Xr carp 4 88interfaces this equals the init state. 89.El 90.Pp 91In contrast to link state tests, external tests must be run periodically to 92evaluate their status. 93The frequency at which an external test is run is set, in seconds, with the 94.Ar every 95keyword. 96.Pp 97For example: 98.Bd -literal -offset indent 99links_up = "em0.link.up && em1.link.up" 100net = '( "ping -q -c 1 -w 1 192.168.0.1 > /dev/null" every 10 && \e 101 "ping -q -c 1 -w 1 192.168.0.2 > /dev/null" every 10 )' 102.Ed 103.Sh TESTS AND EVENTS 104.Xr ifstated 8 105delegates the process of testing to libevent which associates a value with 106every test, in this case 107.Em true 108or 109.Em false . 110Whenever the value of a test associated with the current state changes, 111an event is triggered and the state's body is processed. 112.Sh STATE DEFINITIONS 113.Xr ifstated 8 114operates on a finite state machine with states and transitions. 115.Pp 116Each state consists of an 117.Em init 118block and a body. 119The 120.Em init 121block is used to initialise the state and is executed each time the state 122is entered. 123The body of a state is only executed when that state is the current state 124and an event occurs. 125.Pp 126The action taken within a certain state is typically made dependent on the 127evaluation of one or more 128.Em if 129statements. 130Possible actions include executing commands using the 131.Em run 132statement, or triggering a state transition with the 133.Ar set-state 134keyword. 135It is also possible to write multiple nested 136.Em if 137blocks. 138.Pp 139For example: 140.Bd -literal -offset indent 141state one { 142 init { 143 run "logger -t ifstated entering state one" 144 run "ifconfig -g carp -carpdemote" 145 } 146 147 if ! $net || urndis0.link.up 148 set-state two 149 150 if ! $links_up { 151 run "ifconfig -g carp carpdemote" 152 153 if urndis0.link.down 154 set-state three 155 } 156} 157.Ed 158.Sh GRAMMAR 159Syntax for 160.Nm 161in BNF: 162.Bd -literal 163grammar = entry grammar | entry 164 165entry = global_config | varset | action | state 166 167global_config = initstate 168initstate = "init-state" string 169 170varset = string "=" string 171 172action_list = action [ action_list ] 173action = "run" string | "set-state" string | 174 "if" expr action_block 175action_block = "{" action_list "}" | action 176expr = "!" expr | expr "&&" expr | expr "||" expr | term 177term = if_test | ext_test | "(" expr ")" 178if_test = string ".link." ( "up" | "down" | "unknown" ) 179ext_test = string "every" number 180 181state = "state" string "{" stateopt_list "}" 182stateopt_list = stateopt [ stateopt_list ] 183stateopt = init | action 184init = "init" action_block 185.Ed 186.Sh FILES 187.Bl -tag -width /etc/examples/ifstated.conf -compact 188.It Pa /etc/ifstated.conf 189.Xr ifstated 8 190configuration file. 191.It Pa /etc/examples/ifstated.conf 192Example configuration file. 193.El 194.Sh SEE ALSO 195.Xr carp 4 , 196.Xr pf 4 , 197.Xr ifstated 8 198.Sh HISTORY 199The 200.Nm 201file format first appeared in 202.Ox 3.8 . 203