summaryrefslogtreecommitdiffstats
path: root/docs/netcfg-profiles.5.txt
blob: f929e4778eb4d92b83a17c5f7e80d3179593a3dc (plain)
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
NETCFG-PROFILES(5)
==================

NAME
----
netcfg-profiles - netcfg profiles documentation and syntax


DESCRIPTION
-----------
The *netcfg*(8) profiles are plain text files that defines variables for
netcfg behavior. They must be compliant with *bash*(1) shell syntax and
usually do not execute any code.

They are named '/etc/network.d/$\{profile_name}', where
+$\{profile_name\}+ must not contain a newline character and should not
start with the `@'-sign.


OVERVIEW
--------
Profiles must define mandatory variables:

+INTERFACE+::
  The name of the associated network interface.
+DESCRIPTION+::
  A description of the profile.
+CONNECTION+::
  The connection type used by the profile.

Connections define how the network is set up for the profile and also
determine additional configuration variable that control their
behavior. The available connection types are determined by files in
'/usr/lib/network/connections/'.


Available connections
---------------------
ethernet::
  Standard network configuration, suitable for wired connections.
wireless::
  Wireless connection, with *wpa_supplicant*(1) as configuration
  back-end.
bond::
  Bonded network interfaces using *ifenslave*.
bridge::
  Network bridge setup using *brctl*(8).
tuntap::
  TUN/TAP interfaces.
tunnel::
  Tunnel interfaces.
vlan::
  VLAN setup.
openvpn::
  OpenVPN setup.
ppp::
  PPP connections setup.
pppoe::
  PPPoE connections setup.

The configuration variable for these connection types is described in
the following sections.


Ethernet options reference
--------------------------

Description
~~~~~~~~~~~
This connection method uses the iproute suite of tools and dhcpcd to
gain an IP address.

+IP+ (required for IPv4)::
  Either `static' or `dhcp'. Set to `no' to have netcfg bring the interface
  up but assign no addresses. Static requires at least one of +ADDR+ or
  +IPCFG+.

IPv4 options
~~~~~~~~~~~~
+ADDR+ (requires +IP+ of `static')::
  A single IP address to configure a static IP.
+GATEWAY+ (requires +IP+ of `static')::
  Set specified gateway
+NETMASK+ (requires +IP+ of `static')::
  Set specified netmask. Defaults to 24.
+ROUTES+::
  An array of custom routes (of the form _address range_ via _gateway_)

IPv6 options
~~~~~~~~~~~~
+IP6+ (required for IPv6)::
  Either `dhcp', `dhcp-noaddr', `stateless', `static'. Set to `no' to
  disable IPv6.
+ADDR6+ (required when +IP6+ is `static')::
  An array of IPv6 addresses: prefix length may be specified via
  `1234:bcd::11/64' syntax.
+GATEWAY6+ (requires +IP6+ of `static')::
  The gateway address for IPv6 routing.
+ROUTES6+::
  An array of custom routes (of the form _address range_ via _gateway_)
+DAD_TIMEOUT+::
  Time to wait for Duplicate Address Detection to succeed. Defaults to
  3 seconds.

DNS configuration
^^^^^^^^^^^^^^^^^
+DNS+::
  Array of DNS nameservers. Simply specify the IP's of each of the DNS
  nameservers.
+DNS_OPTIONS+::
  Array of ``option'' lines for '/etc/resolv.conf'
+SEARCH+::
  ``search'' line for '/etc/resolv.conf'
+DOMAIN+::
  ``domain'' line for '/etc/resolv.conf'
+HOSTNAME+::
  Set the system hostname. Ensure any hostname is correctly referenced
  in '/etc/hosts'

DHCP configuration
^^^^^^^^^^^^^^^^^^
+DHCP_OPTIONS+ (ipv4)::
  String. Any extra arguments to pass to the dhcp client, presently
  dhcpcd.
+DHCP_TIMEOUT+::
  Integer. Maximum time to try for a DHCP IP. Default is 10 seconds.
+DHCLIENT+::
  yes/no. Use dhclient instead of dhcpcd. Defaults to no
+DHCLIENT_OPTIONS+ (ipv4)::
  String. Extra options to pass to dhclient for IPv4.
+DHCLIENT6_OPTIONS+ (ipv6)::
  String. Extra options to pass to dhclient for IPv6.

802.11x Authentication
^^^^^^^^^^^^^^^^^^^^^^
+AUTH8021X+::
  Use 802.11x authentication. Enable with `yes'.
+WPA_CONF+ (required for an +AUTH8021X+ of `yes' only)::
  Path to wpa_supplicant configuration. Defaults to
  '/etc/wpa_supplicant.conf'
+WPA_OPTS+ (optional for an +AUTH8021X+ of `yes')::
  Extra arguments for wpa_supplicant not specified otherwise. Any option
  here must specify wpa_supplicant driver. Defaults to _-Dwired_.

Miscellaneous options
^^^^^^^^^^^^^^^^^^^^^
+IPCFG+::
  Array of arguments to pass to `ip`. The power of this options is that
  it allows both simple and complicated routing configurations, within
  the framework of netcfg.
+SKIPNOCARRIER+::
  `yes'/`no'. Don't abort interface setup if no carrier is found.


Examples
~~~~~~~~

Using ADDR and GATEWAY to set static IP and gateway
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---------------------
IP="static"
ADDR="192.168.1.23"
GATEWAY="192.168.1.1"
---------------------

Using IPCFG to set a static IP and gateway with custom DNS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-------------------------------------------------------------------------------------
IP="static"
IPCFG=("addr add dev eth0 192.168.1.23/24 brd +" "route add default via 192.168.1.1")
DNS=("208.67.222.222" "208.67.220.220")
-------------------------------------------------------------------------------------


Wireless options reference
--------------------------

Description
~~~~~~~~~~~
This connection method uses wpa_supplicant to configure a wireless
network connection. This connection uses the 'ethernet' connection after
successful association and thus supports all of its options.

Options
~~~~~~~
+SECURITY+ (required for security of `wep', `wpa', `wpa-configsection' or `wpa-config')::
  One of `wpa', `wep', `none', `wpa-configsection' or `wpa-config'.
  Defaults to `none'.
+KEY+ (required for +SECURITY+ of `wpa' or `wep' only)::
  Wireless encryption key.
+ESSID+ (this or +AP+ is required)::
  Name of network to connect to, or hexadecimal digits (see
  `ESSID_TYPE')
+ESSID_TYPE+ (optional, defaults to `ascii')::
  Set to `ascii' or `hex', if set to `hex', +ESSID+ will be interpreted as
  an hexadecimal +SSID+ and written unquoted to the wpa_supplicant
  configuration file.
+AP+ (this or +ESSID+ is required)::
  AP (BSSID) of the network to connect to.
+HIDDEN+ (optional)::
  Define this to connect to hidden ESSIDs.
+ADHOC+ (optional)::
  Define this to use ad-hoc mode for wireless.
+TIMEOUT+ (optional)::
  Time to wait for association. Defaults to 15 seconds.
+SCAN+ (optional)::
  `yes'/`no'. Scan for a wireless network rather than blindly attempting to
  connect. Hidden SSID networks do not appear in a scan.
+PRIORITY+ (optional)::
  Priority group for the network. The matched network with the highest
  priority will be selected. Defaults to 0.

WPA options
^^^^^^^^^^^
+WPA_CONF+ (for +SECURITY+ of `wpa-config' only)::
  Path to wpa_supplicant configuration. Defaults to
  '/etc/wpa_supplicant.conf'
+WPA_OPTS+::
  Extra arguments for wpa_supplicant not specified otherwise.
+WPA_GROUP+::
  Group that has authority to configure wpa_supplicant via it's control
  interface. Used in any configuration that is generated by netcfg.
+WPA_COUNTRY+ (optional, nl80211 based drivers)::
  The country where the device will be used. This allows wpa_supplicant
  to enforce any local regulatory limitations and will allow all
  appropriate channels/frequencies for your device.
+WPA_DRIVER+ (optional)::
  A comma-separated list of wpa_supplicant driver interfaces to try.
  Defaults to `nl80211,wext'.

rfkill (Radio Kill Switch) options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+RFKILL+::
  hard/soft A switch with physical on/off state that cannot be
  controlled via software is considered a *hard* switch. Any switch that
  can be controlled via software is considered *soft*.
+RFKILL_NAME+::
  Some switches sysfs entries are not linked with the interface. To
  match them up, configure the name from '/sys/class/rfkill/rfkillX/name'
  here so that netcfg can identify which to control.


Options for `bridge' connections
--------------------------------
The options of `ethernet' connections apply to set up standard IP
connectivity.

+BRIDGE_INTERFACES+::
  List of network interfaces taking part in the bridge.
+FWD_DELAY+::
  Forward delay of the bridge, see *brctl*(8)
+MAX_AGE+::
  maxage parameter, see *brctl*(8)


Options for `tuntap' connections
--------------------------------
The options of `ethernet' connections apply to set up standard IP
connectivity.

+MODE+::
  Set to `tun' or `tap'.
+USER+::
  The owning user of the tun/tap interface.
+GROUP+::
  The owning group of the tun/tap interface.


Options for `ppp' connections
-----------------------------
+PEER+::
  The *pppd*(8) peer to use.
+PPP_TIMEOUT+::
  *pppd*(8) timeout.


Options for `vlan' connections
------------------------------
+INTERFACE+::
  The name of the virtual interface.
+VLAN_PHYS_DEV+::
  The name of the associated physical interface.
+VLAN_ID+::
  See *ip*(8).


Options for `tunnel' connections
--------------------------------
Standard `ethernet' options apply for IP configuration.

+INTERFACE+::
  The name of the tunnel interface.
+MODE+::
  The tunnel type (e.g. `sit'). See *ip*(8) for available modes.
+LOCAL+::
  The address of the local end of the tunnel.
+REMOTE+::
  The address of the remote end of the tunnel.


Options for `bond' connections
------------------------------
Standard `ethernet' options apply for IP configuration.

+SLAVE_INTERFACES+ (Bash array)::
  An array of names of interfaces to be bound together.


Options for `openvpn' connections
---------------------------------
+OVPN_CONFIG+::
  Path to the *openvpn*(8) config file.
+OVPN_PID_FILE+::
  Path to the *openvpn*(8) PID file.
+OVPN_FLAGS+::
  Options to pass to *openvpn*(8) invocation.


SEE ALSO
--------
include::footer.txt[]