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