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