1.\" $OpenBSD: ifstated.conf.5,v 1.9 2012/04/24 14:56:09 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: April 24 2012 $ 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.Sh SECTIONS 32The 33.Nm 34config file is divided into three 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. 58Macro names may not be reserved words like, for example 59.Ar state 60or 61.Ar run . 62Macros are referenced with a shell-like notation as 63.Em $macro . 64Macros are usually used to define tests for state transitions like interface 65link state or external tests. 66.Pp 67Currently an interface can have three different link states: 68.Pp 69.Bl -tag -width xxxxxxxx -compact 70.It Ar up 71The physical link of the interface is up. 72For 73.Xr carp 4 74interfaces this equals the master state. 75.It Ar down 76The physical link of the interface is down. 77For 78.Xr carp 4 79interfaces this equals the backup state. 80.It Ar unknown 81The physical link of the interface is unknown. 82This is because the interface driver does not provide information of the 83physical link state. 84For 85.Xr carp 4 86interfaces this equals the init state. 87.El 88.Pp 89In contrast to link state tests, external tests must be run periodically to 90evaluate their status. 91The frequency at which an external test is run has to be set with the 92.Ar every 93keyword. 94.Pp 95For example: 96.Bd -literal -offset indent 97carp_up = "carp0.link.up && carp1.link.up" 98net = '( "ping -q -c 1 -w 1 192.168.0.1 > /dev/null" every 10 && \e 99 "ping -q -c 1 -w 1 192.168.0.2 > /dev/null" every 10 )' 100.Ed 101.Sh TESTS AND EVENTS 102.Xr ifstated 8 103delegates the process of testing to libevent which associates a value with 104every test, in this case 105.Em true 106or 107.Em false . 108Whenever the value of a test associated with the current state changes, 109an event is triggered and the state's body is processed. 110.Sh STATE DEFINITIONS 111.Xr ifstated 8 112operates on a finite state machine with states and transitions. 113.Pp 114Each state consists of an 115.Em init 116block and a body. 117The 118.Em init 119block is used to initialise the state and is executed each time the state 120is entered. 121The body of a state is only executed when that state is the current state 122and an event occurs. 123.Pp 124The action taken within a certain state is typically made dependent on the 125evaluation of one or more 126.Em if 127statements. 128Possible actions include executing commands using the 129.Em run 130statement, or triggering a state transition with the 131.Ar set-state 132keyword. 133It is also possible to write multiple nested 134.Em if 135blocks. 136.Pp 137For example: 138.Bd -literal -offset indent 139state one { 140 init { 141 run "ifconfig carp0 advskew 10" 142 run "ifconfig carp1 advskew 10" 143 } 144 145 if ! $net 146 set-state two 147 148 if ! $carp_up { 149 run "ifconfig carp0 advskew 254" 150 run "ifconfig carp1 advskew 254" 151 set-state three 152 } 153} 154.Ed 155.Sh GRAMMAR 156Syntax for 157.Nm 158in BNF: 159.Bd -literal 160grammar = entry grammar | entry 161 162entry = global_config | varset | action | state 163 164global_config = initstate 165initstate = "init-state" string 166 167varset = string "=" string 168 169action_list = action [ action_list ] 170action = "run" string | "set-state" string | 171 "if" expr action_block 172action_block = "{" action_list "}" | action 173expr = "!" expr | expr "&&" expr | expr "||" expr | term 174term = if_test | ext_test | "(" expr ")" 175if_test = string ".link." ( "up" | "down" | "unknown" ) 176ext_test = string "every" number 177 178state = "state" string "{" stateopt_list "}" 179stateopt_list = stateopt [ stateopt_list ] 180stateopt = init | action 181init = "init" action_block 182.Ed 183.Sh FILES 184.Bl -tag -width "/etc/ifstated.conf" -compact 185.It Pa /etc/ifstated.conf 186.Xr ifstated 8 187configuration file 188.El 189.Sh SEE ALSO 190.Xr carp 4 , 191.Xr pf 4 , 192.Xr ifstated 8 193.Sh HISTORY 194The 195.Nm 196file format first appeared in 197.Ox 3.8 . 198