-
Notifications
You must be signed in to change notification settings - Fork 1
/
ngbuddy.8
362 lines (362 loc) · 10.3 KB
/
ngbuddy.8
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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
.\" Automatically generated by Pandoc 3.1.13
.\"
.TH "ngbuddy" "8" "July 8, 2024" "" "System Manager\[cq]s Manual"
.SH NAME
\f[B]ngbuddy\f[R] \- Simplified netgraph(4) manager for jail(8) and
bhyve(8)
.SH SYNOPSIS
\f[B]service ngbuddy enable\f[R]
.PD 0
.P
.PD
\f[B]service ngbuddy start\f[R]
.PD 0
.P
.PD
\f[B]service ngbuddy stop\f[R]
.PD 0
.P
.PD
\f[B]service ngbuddy restart\f[R]
.PD 0
.P
.PD
\f[B]service ngbuddy status\f[R]
.PP
\f[B]service ngbuddy bridge\f[R] \f[I]bridge\f[R] \f[I]interface\f[R]
.PD 0
.P
.PD
\f[B]service ngbuddy unbridge\f[R] \f[I]bridge\f[R]
.PP
\f[B]service ngbuddy jail\f[R] \f[I]interface\f[R] [\f[I]bridge\f[R]]
.PD 0
.P
.PD
\f[B]service ngbuddy unjail\f[R] \f[I]interface\f[R] [\f[I]jail\f[R]]
.PD 0
.P
.PD
\f[B]service ngbuddy create\f[R] \f[I]interface\f[R] [\f[I]bridge\f[R]]
.PD 0
.P
.PD
\f[B]service ngbuddy destroy\f[R] \f[I]interface\f[R]
.PP
\f[B]service ngbuddy vmconf\f[R]
.PD 0
.P
.PD
\f[B]service ngbuddy vmname\f[R]
.SH DESCRIPTION
\f[B]ngbuddy\f[R] (\[lq]Netgraph Buddy\[rq]) is an rc.d script for
managing netgraph(4) in mixed vm and jail environments.
Netgraph provides a more flexible networking solution compared to the
traditional if_bridge/epair/tap setup, offering a clearer and shorter
list of virtual devices, and performance benefits for some workloads.
.PP
\f[B]rc.conf\f[R] variables prefixed by \f[B]ngbuddy_\f[R] are used to
manage ng_bridge(4) and ng_eiface(4) devices upon service start (and
system boot).
Additional tools assist with jail interface management, configuring
vm\-bhyve, naming vm\-bhyve sockets, displaying basic statistics, and
determining stable MAC addresses to help avoid collisions.
.SH QUICK START EXAMPLE
The following commands will configure a system for netgraph.
.TP
\f[B]service ngbuddy enable\f[R]
Sets \f[B]rc.conf\f[R] variables to enable the ngbuddy service.
If no bridge definitions are set, the following default bridge
definitions will be added:
.PD 0
.P
.PD
\f[I]public\f[R]: A bridge interface associated with the host
system\[cq]s current default route, allowing guests to interact with the
existing network.
.PD 0
.P
.PD
\f[I]private\f[R]: A bridge linked to a new virtual interface named
\f[B]nghost0\f[R], suitable for host\-only or NAT network with your
guests.
.PD 0
.P
.PD
.IP
.EX
ngbuddy_enable=\[dq]YES\[dq]
ngbuddy_public_if=\[dq]em0\[dq]
ngbuddy_private_if=\[dq]nghost0\[dq]
.EE
.TP
\f[B]service ngbuddy start\f[R]
Creates bridges and interfaces defined in \f[B]rc.conf\f[R].
.TP
\f[B]service ngbuddy vmconf\f[R]
Adds our \f[I]public\f[R] and \f[I]private\f[R] bridges to the vm(8)
configuration, as a substitute for the \f[B]vm switch \&...\f[R]*
commands.
.PP
To get the most out of the \f[I]private\f[R] bridge, configure
\f[B]nghost0\f[R] with an IP address and add a NAT service to allow your
guests to have access to the network.
See the \f[B]examples\f[R] in the \f[B]ngbuddy\f[R] repository for demo
scripts.
.SH SUBCOMMANDS
Subcommands are called using \f[B]service ngbuddy\f[R]
\f[I]SUBCOMMAND\f[R].
Note that all commands rely on ngctl(8) and require root permissions.
.TP
\f[B]enable\f[R]
Enable the \f[B]ngbuddy\f[R] service.
If no bridges are defined, a \f[I]public\f[R] and \f[I]private\f[R]
bridge will be created.
See \f[I]QUICK START EXAMPLE\f[R] above for details.
.TP
\f[B]start\f[R]
Load the bridge and eiface options configured in \f[B]rc.conf\f[R].
See \f[I]RC.CONF VARIABLES\f[R] below for a complete list of options.
.TP
\f[B]stop\f[R]
Destroy all ng_bridge(4) and ng_eiface(4) devices, even if they were not
created with \f[B]ngbuddy\f[R].
.TP
\f[B]restart\f[R]
Stop, then start.
.TP
\f[B]status\f[R]
Print a list of ng_bridge(4), ng_eiface(4), and ng_socket(4) devices and
basic usage statistics.
.TP
\f[B]bridge\f[R] \f[I]bridge\f[R] \f[I]interface\f[R]
Create a bridge and an associated \f[B]rc.conf\f[R] entry.
If the \f[I]interface\f[R] exists, \f[I]bridge\f[R] will be associated
with it.
Otherwise, \f[I]interface\f[R] will be created as a new eiface node.
.TP
\f[B]unbridge\f[R] \f[I]bridge\f[R]
Remove the indicated bridge from netgraph and \f[B]rc.conf\f[R].
.TP
\f[B]jail\f[R] \f[I]interface\f[R] [\f[I]bridge\f[R]]
Create a new eiface associated with the indicated \f[I]bridge\f[R].
If only one ng_bridge(4) is present, \f[I]bridge\f[R] may be omitted.
.TP
\f[B]unjail\f[R] \f[I]interface\f[R] [\f[I]jail\f[R]]
Shut down the eiface associated with the indicated \f[I]jail\f[R].
If the \f[I]interface\f[R] matches the jail name, \f[I]jail\f[R] may be
omitted.
.TP
\f[B]create\f[R] \f[I]interface\f[R] [\f[I]bridge\f[R]]
Create a new eiface associated with the indicated \f[I]bridge\f[R] and
add it to \f[B]rc.conf\f[R] so it will be created on startup.
If only one bridge is configured, \f[I]bridge\f[R] may be omitted.
.TP
\f[B]destroy\f[R] \f[I]interface\f[R]
Shut down the indicated eiface and remove it from \f[B]rc.conf\f[R].
.TP
\f[B]vmconf\f[R]
Add the bridges configured in \f[B]rc.conf\f[R] to the vm(8)
configuration, e.g., \f[B]/vm/.config/system.conf\f[R].
.TP
\f[B]vmname\f[R]
Name ng_socket(4) devices associated with bhyve instances running via
vm(8).
.SH RC.CONF VARIABLES
The following variables can be manually configured.
Some of the above subcommands will use sysrc(8) to configure rc.conf
with the following variables for persistent configuration on service
restart or system reboot.
.TP
\f[I]ngbuddy_enable\f[R]
Set to \f[I]YES\f[R] to enable the service.
.TP
\f[I]ngbuddy_(\f[R]BRIDGE\f[I])_if\f[R]
Link a new ng_bridge(4) device named \f[I]BRIDGE\f[R] to the indicated
interface, e.g., \f[I]eth0\f[R].
If the interface already exists, link it to the new bridge and disable
LRO/TSO.
If the interface does not exist, create it as an ng_eiface(4) device.
This variable will be set with the \f[B]bridge\f[R] and
\f[B]unbridge\f[R] subcommands.
.TP
\f[I]ngbuddy_(\f[R]BRIDGE\f[I])_list\f[R]
A space delimited list of additional ng_eiface(4) devices that will be
attached to \f[I]BRIDGE\f[R] at startup.
This variables will be set with the \f[B]create\f[R] and
\f[B]destroy\f[R] subcommands.
.TP
\f[I]ngbuddy_set_mac\f[R]
If set to \f[I]YES\f[R], eiface hardware addresses will be determined
from a hash of the interface name, ensuring that the interfaces\[cq] MAC
address are stable between hosts.
If set to a string besides \f[I]YES\f[R], that string will be added to
the MAC address generator\[cq]s seed.
.TP
\f[I]ngbuddy_set_mac_prefix\f[R]
Override the default MAC address prefix of \f[B]58:9C:FC\f[R] (the OUI
of the FreeBSD Foundation).
For example, you can set \f[I]ngbuddy_set_mac_prefix=\[lq]02\[rq]\f[R]
to minimize the risk of collisions.
\f[I]ngbuddy_set_mac\f[R] must also be enabled to use this feature.
.TP
\f[I]ngbuddy_set_mac_hash\f[R]
Override the default hash command of \f[B]sha1\f[R] with the command
indicated.
The command\[cq]s output will receive the seed through standard input
(see \f[I]ngbuddy_set_mac\f[R]) and must return enough hexadecimal
characters to complete the MAC address.
.SH FILES
.TP
\f[B]/usr/local/etc/rc.d/ngbuddy\f[R]
The Netgraph Buddy run control script.
.TP
\f[B]/usr/local/share/ngbuddy/ngbuddy\-status.awk\f[R]
Helper for \f[B]service ngbuddy status\f[R]
.TP
\f[B]/usr/local/share/ngbuddy/ngbuddy\-mmd.awk\f[R]
An alternative to \f[B]ngctl dot\f[R] that creates a Mermaid\-JS color
diagram of netgraph nodes.
.SH EXAMPLES
For examples and demo scripts, see \f[B]examples\f[R] at:
https://github.com/bellhyve/netgraph\-buddy
.PP
\f[B]Example 1: Quickly deploy a VNET jail with netgraph using
jail.conf.d\f[R]
.PP
The following steps will configure a jail attached to the interface
associated with the host\[cq]s current default route, likely your LAN,
using DHCP.
.PP
First, set up Netgraph Buddy:
.PD 0
.P
.PD
\- \f[B]service ngbuddy enable\f[R]
.PD 0
.P
.PD
\- \f[B]service ngbuddy start\f[R]
.PD 0
.P
.PD
\- Append \f[B]examples/devfs.rules\f[R] to \f[B]/etc/devfs.rules\f[R]
.PD 0
.P
.PD
.PP
Next, create a new jail:
.PD 0
.P
.PD
\- Set up a FreeBSD base: \f[B]bsdinstall jail /jail/my_jail\f[R]
.PD 0
.P
.PD
\- Enable DHCP in the jail: \f[B]sysrc \-f /jail/my_jail/etc/rc.conf
ifconfig_DEFAULT=SYNCDHCP\f[R]
.PD 0
.P
.PD
.PP
Configure the jail configuration:
.PD 0
.P
.PD
\- Copy \f[B]examples/jail_skel.conf\f[R] to
\f[B]/etc/jail.conf.d/my_jail.conf\f[R]
.PD 0
.P
.PD
\- In \f[B]my_jail.conf\f[R] after the comments, change the word
\f[B]jail_skel\f[R] to your jail\[cq]s name, \f[B]my_jail\f[R]
.PD 0
.P
.PD
\- Run: \f[B]service jail start my_jail\f[R]
.PD 0
.P
.PD
.PP
To create more jails, you can:
.PD 0
.P
.PD
\- Copy \f[B]/jail/my_jail/\f[R] to \f[B]/jail/new_jail1/\f[R]
.PD 0
.P
.PD
\- Copy \f[B]/etc/jail.conf.d/my_jail.conf\f[R] to
\f[B]new_jail1.conf\f[R]
.PD 0
.P
.PD
\- Edit the new configuration as above and change the word
\f[B]my_jail\f[R] to \f[B]new_jail1\f[R]
.PD 0
.P
.PD
\- Run: \f[B]service jail start new_jail1\f[R]
.PD 0
.P
.PD
\- And repeat as desired.
.PD 0
.P
.PD
.PP
\f[B]Example 2: An rc.conf example for a slightly more complex
setup\f[R]
.IP
.EX
ngbuddy_enable=\[dq]YES\[dq]
ngbuddy_lan_if=\[dq]igb0\[dq]
ngbuddy_private0_if=\[dq]ng0\[dq]
ngbuddy_private0_list=\[dq]j1p0 j2p0\[dq]
ngbuddy_private1_if=\[dq]ng1\[dq]
ngbuddy_private1_list=\[dq]j1p1 j2p1\[dq]
ngbuddy_tenant_lan_if=\[dq]igb1\[dq]
ngbuddy_tenant_wan_if=\[dq]ix1\[dq]
ngbuddy_wan_if=\[dq]ix0\[dq]
ngbuddy_set_mac=\[dq]belltower\[dq]
ngbuddy_set_mac_prefix=\[dq]02\[dq]
ngbuddy_set_mac_hash=\[dq]sha256\[dq]
.EE
.PP
\f[B]Example 3: Initial status of the above configuration\f[R]
.IP
.EX
lan
igb0 \f[B](\f[R]upper\f[B])\f[R]: RX 0B, TX 0B
igb0 \f[B](\f[R]lower\f[B])\f[R]: RX 0B, TX 0B
private0
j2p0: RX 0B, TX 0B
j1p0: RX 0B, TX 0B
ng0: RX 0B, TX 0B
private1
j2p1: RX 0B, TX 0B
j1p1: RX 0B, TX 0B
ng1: RX 0B, TX 0B
tenant_lan
igb1 \f[B](\f[R]upper\f[B])\f[R]: RX 0B, TX 0B
igb1 \f[B](\f[R]lower\f[B])\f[R]: RX 0B, TX 0B
tenant_wan
ix1 \f[B](\f[R]upper\f[B])\f[R]: RX 0B, TX 0B
ix1 \f[B](\f[R]lower\f[B])\f[R]: RX 0B, TX 0B
wan
ix0 \f[B](\f[R]upper\f[B])\f[R]: RX 30.69 KB, TX 46.16 KB
ix0 \f[B](\f[R]lower\f[B])\f[R]: RX 46.32 KB, TX 30.92 KB
.EE
.SH NOTES
These scripts were developed to assist with new netgraph features in
\f[B]vm\-bhyve 1.5+\f[R], and were inspired by the
\f[B]/usr/share/examples/jails/jng\f[R] example script and additional
examples by Klara Systems.
.SH SEE ALSO
jail(8), netgraph(4), ng_bridge(4), ngctl(8), ng_eiface(4),
ng_socket(4), vm(8)
.SH HISTORY
Netgraph Buddy was originally developed as an internal tool for Bell
Tower Integration\[cq]s private cloud in August 2022.
.SH AUTHORS
Daniel J. Bell.