summaryrefslogtreecommitdiffstats
path: root/docs/netctl.profile.5.txt
blob: 45f9b3ea6d92a7f16abf8a5bf35e3ace80bf741c (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
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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
NETCTL.PROFILE(5)
=================

NAME
----
netctl.profile - Profile options


SYNOPSIS
--------
netctl.profile


DESCRIPTION
-----------
Profiles for netctl live under '/etc/netctl/' and are plain text files.
The files consist of variable definitions following the bash shell
syntax and are not expected to execute any code. It is good to omit as
much quoting as possible. For a few WPA-related variables, special
quoting rules (see below) apply.

The name of the profile is the name of the file. Profile names must not
contain newlines and should not end in '.action', '.conf', or
'.service'. Whenever a profile is read, all executable scripts in
'/etc/netctl/hooks/' and any executable script in
'/etc/netctl/interfaces/' with the name of the interface for the profile
are sourced. Declarations in an interface script override declarations
in a profile, which override declarations in hooks. For each connection
type, there are example profile files in '/etc/netctl/examples/'.


AVAILABLE CONNECTION TYPES
--------------------------
+ethernet+::
    For wired connections.
+wireless+::
    For wireless connections. This connection type requires
    *wpa_supplicant* to be available.
+bond+::
    For bonded interfaces.
+bridge+::
    For bridge interfaces.
+dummy+::
    For dummy interfaces.
+ppp+::
    For PPP connections (currently only PPPoE).
+pppoe+::
    For PPPoE connections.
+mobile_ppp+::
    For mobile broadband PPP connections that use a USB modem.
+tunnel+::
    For tunnel interfaces.
+tuntap+::
    For TUN/TAP interfaces.
+vlan+::
    For VLANs on ethernet-like connections.
+macvlan+::
    For MACVLANs on ethernet-like connections.


GENERAL OPTIONS
---------------
'Description='::
    A description of the profile.

'Connection=' [mandatory for all profiles]::
    The connection type used by the profile.

'Interface=' [mandatory for all profiles]::
    The name of the associated network interface. The interface name
    should not be quoted.

'BindsToInterfaces=()'::
    An array of physical network interfaces that this profile needs
    before it can be started. For `enabled' profiles, *systemd* will
    wait for the presence of the specified interfaces before starting a
    profile. If this variable is not specified, it defaults to the value
    of 'Interface'.

'After=()'::
    An array of profile names that should be started before this profile
    is started. This is only an ordering dependency and is not intended
    to be a list of profiles that this profile requires. The meaning is
    the same as 'After' in *systemd.unit*(5).

'ExecUpPost='::
    A command that is executed after a connection is established. If the
    specified command returns anything other than 0 (success), *netctl*
    will abort and stop the profile. If the command should be allowed to
    fail, add ``|| true`' to the end of it.

'ExecDownPre='::
    A command that is executed before a connection is brought down.
    Similar precautions should be taken as with 'ExecUpPost'.

'TimeoutUp'::
    Maximum time, in seconds, to wait for an interface to get up.
    Defaults to `++5++'.

'ForceConnect='::
    Set to `++yes++' to force connecting even if the interface is up.
    Do not use this unless you know what you are doing.


IP OPTIONS
----------
These options apply to all connections that set up an IP-enabled
network. In particular, these connection types are +ethernet+,
+wireless+, +bond+, +bridge+, +tunnel+, +tuntap+, and +vlan+.

'IP=' [mandatory for IPv4]::
    One of `static', `dhcp', or `no', depending on the desired way of
    obtaining an address.

'IP6=' [mandatory for IPv6]::
    One of `static', `stateless', `dhcp-noaddr', `dhcp', `no' or left
    out (empty) altogether. The difference between not specifying and
    setting to `no' is in the handling of __router advertisement__
    packages, which is blocked by `no'.

'Address=()' [requires 'IP=static']::
    An array of IP addresses suffixed with `++/<netmask>++'.
    Leaving out brackets for arrays consisting of a single element is
    accepted in the Bash syntax.

'Gateway=' [requires 'IP=static']::
    An IP routing gateway address.

'Routes='::
    An array of custom routes of the form +
    `**<address range>** via **<gateway>**'.

'Address6=()' [requires 'IP6=static' or 'IP6=stateless']::
    An array of IPv6 addresses. Prefix length may be specified via
    `1234:bcd::11/64' syntax. It is possible to specify modifiers, in
    particular, `1234:bcd::11/64 nodad' disables Duplicate Address
    Detection for the address.

'Gateway6=' [requires 'IP6=static' or 'IP6=stateless']::
    An IPv6 routing gateway address.

'Routes6='::
    An array of custom routes of the form +
    `**<address range>** via **<gateway>**'.

'DHCPClient=' [requires 'IP=dhcp']::
    The name of the DHCP client to use. Clients may accept additional
    options through client-specific variables. By default, *netctl*
    comes with support for `dhcpcd' and `dhclient'. Defaults to
    `++dhcpcd++'.

'DHCP6Client=' [requires 'IP6=dhcp' or 'IP6=dhcp-noaddr']::
    The name of the DHCPv6 client to use. By default, only `dhclient'
    is supported. Defaults to `++dhclient++'.

'DHCPReleaseOnStop='::
    Set to `++yes++' to release the DHCP lease when the profile is
    stopped.

'IPCustom=()'::
    An array of argument lines to pass to `ip`. This can be used to
    achieve complicated configurations within the framework of *netctl*.

'Hostname='::
    A system hostname.

'DNS=()'::
    An array of DNS nameservers. Simply specify the IP addresses of each
    of the DNS nameservers.

'DNSDomain='::
    A `++domain++' line for '/etc/resolv.conf', passed to
    *resolvconf*(5).

'DNSSearch='::
    A `++search++' line for '/etc/resolv.conf', passed to
    *resolvconf*(5).

'DNSOptions=()'::
    An array of `++options++' lines for '/etc/resolv.conf', passed to
    *resolvconf*(5).

'TimeoutDHCP='::
    Maximum time, in seconds, to wait for DHCP to be successful.
    Defaults to `++30++'.

'TimeoutDAD='::
    Maximum time, in seconds, to wait for IPv6's Duplicate Address
    Detection to succeed. Defaults to `++3++'.

'SkipDAD='::
    Whether or not to bypass Duplicate Address Detection altogether.
    Defaults to `++no++'.


OPTIONS FOR `ethernet' CONNECTIONS
----------------------------------
Next to the *ip options*, the following are understood for connections
of the `ethernet' type:

'Auth8021X='::
    Set to `++yes++' to use 802.1x authentication.

'WPAConfigFile='::
    Path to a *wpa_supplicant* configuration file. Defaults to
    '/etc/wpa_supplicant.conf'.

'WPADriver='::
    The *wpa_supplicant* driver to use for 802.1x authentication.
    Defaults to `++wired++'.

'TimeoutCarrier='::
    Maximum time, in seconds, to wait for a carrier. Defaults to
    `++5++'.

'TimeoutWPA='::
    Maximum time, in seconds, to wait for 802.1x authentication to
    succeed. Defaults to `++15++'.

'SkipNoCarrier='::
    Whether or not the absence of a carrier (plugged-in cable) is
    acceptable. Defaults to `++no++'.


OPTIONS FOR `wireless' CONNECTIONS
----------------------------------
Next to the *ip options*, the following are understood for connections
of the `wireless' type:

'Security='::
    One of `none', `wep', `wpa', `wpa-configsection', or `wpa-config'.
    Defaults to `++none++'.

'ESSID=' [mandatory]::
    The name of the network to connect to.
    Special quoting rules (see below) apply.

'AP='::
    The BSSID (MAC address) of the access point to connect to.

'Key='::
    The secret key to a WEP, or WPA encrypted network.
    Special quoting rules (see below) apply.

'Hidden='::
    Whether or not the specified network is a hidden network. Defaults
    to `++no++'.

'AdHoc='::
    Whether or not to use ad-hoc mode. Defaults to `++no++'.

'ScanFrequencies='::
    A space-separated list of frequencies in MHz to scan when searching
    for the network. Defaults to all available frequencies.

'Priority='::
    Priority group for the network. In case of automatic profile
    selection, the matched network with the highest priority will be
    selected. Defaults to `++0++'.

'WPAConfigSection=()' [mandatory for 'Security=wpa-configsection']::
    Array of lines that form a network block for *wpa_supplicant*. All
    of the above options will be ignored.

'WPAConfigFile='::
    Path to a *wpa_supplicant* configuration file. Used only for
    'Security=wpa-config'. All options except 'WPADriver', 'TimeoutWPA',
    and 'RFKill' will be ignored. The profile is excluded from
    automatic profile selection. Defaults to '/etc/wpa_supplicant.conf'.

'Country='::
    The country for which frequency regulations will be enforced.

'WPAGroup='::
    Group that has the authority to configure *wpa_supplicant* via its
    control interface. Defaults to `++wheel++'.

'WPADriver='::
    The *wpa_supplicant* driver to use. Defaults to `++nl80211,wext++'.

'TimeoutWPA='::
    Maximum time, in seconds, to wait for steps in the association and
    authentication to succeed. Defaults to `++15++'.

'RFKill='::
    The name of an *rfkill* device. When specified, the device is used
    to block/unblock the interface when appropriate. Names can be found
    in '/sys/class/rfkill/rfkillX/name'. It is also possible to set this
    variable to `++auto++'. In that case an *rfkill* device that is
    associated with the network interface is used.

'ExcludeAuto='::
    Whether or not to exclude this profile from automatic profile
    selection. Defaults to `++no++'.


OPTIONS FOR `bond' CONNECTIONS
------------------------------
The interfaces of 'BindsToInterfaces' are bound together in the
interface named by 'Interface'. All *ip options* are understood for
connections of the `bond' type.


OPTIONS FOR `bridge' CONNECTIONS
--------------------------------
The interfaces of 'BindsToInterfaces' take part in the bridge named by
'Interface'. Next to the *ip options*, the following is understood for
connections of the `bridge' type:

'SkipForwardingDelay='::
    Skip \(R)STP and immediately activate all bridge members. This can
    be useful when DHCP is used on the bridge.


OPTIONS FOR `dummy' CONNECTIONS
-------------------------------
The name of the dummy interface is sepcified in 'Interface'. Only the
*ip options* are understood for connections of the `dummy' type.


OPTIONS FOR `ppp' CONNECTIONS
-----------------------------
This connection type is identical to the `pppoe' type below, with the
ethernet interface specified in 'BindsToInterfaces'. The value of
'Interface' must be of the form `ppp<++n++>', where ++n++ is passed on as
the value of 'PPPUnit'.


OPTIONS FOR `pppoe' CONNECTIONS
-------------------------------
The interface to dial peer-to-peer over ethernet is specified in
'Interface'. The following options are understood for connections of
the `pppoe' type:

'User=' and 'Password='::
    The username and password to connect with.

'ConnectionMode='::
    This option specifies how a connection should be established, and
    may take either `persist' or `demand' as its argument.

'IdleTimeout='::
    This option specifies the idle time (in seconds) after which `pppd'
    should disconnect. This option is only valid if 'ConnectionMode' is
    set to `demand'.

'MaxFail='::
    The number of consecutive failed connection attempts to tolerate.
    A value of 0 means no limit. Defaults to `++5++'.

'DefaultRoute='::
    Use the default route provided by the peer (defaults to `true')

'UsePeerDNS='::
    Use the DNS provided by the peer (defaults to `true').

'PPPUnit='::
    Set the ppp unit number in the interface name (ppp0, ppp1, etc.).

'LCPEchoInterval=' and 'LCPEchoFailure='::
    These options override default LCP parameters from
    `/etc/ppp/options'.

'OptionsFile='::
    A file to read additional pppd options from.

The following advanced options are also understood:

'PPPoEService='::
    This option specifies the PPPoE service name.

'PPPoEAC='::
    This option specifies the PPPoE access concentrator name.

'PPPoESession='::
    This option specifies an existing session to attach to, and is of
    the form `sessid:macaddr'.

'PPPoEMAC='::
    Only connect to specified MAC address

'PPPoEIP6='::
    Enable IPv6 support


OPTIONS FOR `mobile_ppp' CONNECTIONS
------------------------------------
The name of the USB serial device is specified in 'Interface'. The
following options are understood for connections of the `mobile_ppp'
type:

'MaxFail='::
    The number of consecutive failed connection attempts to tolerate.
    A value of 0 means no limit. Defaults to `++5++'.

'DefaultRoute='::
    Use the default route provided by the peer (defaults to `true')

'UsePeerDNS='::
    Use the DNS provided by the peer (defaults to `true')

'User=' and 'Password='::
    The username and password to connect with. These are unset by
    default, as they are often not required.

'AccessPointName='::
    The access point (apn) to connect on. This is specific to your ISP.

'Pin='::
    If your modem requires a PIN to unlock, use this option.

'Mode='::
    This option is used to specify the connection mode. Can be one of
    `3Gpref', `3Gonly', `GPRSpref', `GPRSonly', `None'. This generates
    AT commands specific to certain Huawei modems; all other devices
    should use `None'.

'OptionsFile='::
    A file to read additional pppd options from.


OPTIONS FOR `tunnel' CONNECTIONS
--------------------------------
The name of the tunnel interface is specified in 'Interface'. Next to
the *ip options*, the following are understood for connections of the
`tunnel' type:

'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 `tuntap' CONNECTIONS
--------------------------------
The name of the tuntap interface is specified in 'Interface'. Next to
the *ip options*, the following are understood for connections of the
`tuntap' type:

'Mode='::
    Either `tun', or `tap'.

'User='::
    The owning user of the tun/tap interface.

'Group='::
    The owning group of the tun/tap interface.


OPTIONS FOR `vlan' CONNECTIONS
------------------------------
The name of the vlan interface is specified in 'Interface'. The
underlying physical interface is specified in 'BindsToInterfaces'.
Hence, for vlan profiles, 'BindsToInterfaces' contains the name of a
single network interface.

All options for connections of the `ethernet' type are understood for
connections of the `vlan' type. Additionally, connections of the `vlan'
type must set a vlan identifier using 'VLANID='. See *ip*(8) for
details.


OPTIONS FOR `macvlan' CONNECTIONS
---------------------------------
The name of the macvlan interface is specified in 'Interface'. The
underlying physical interface is specified in 'BindsToInterfaces'.
Hence, for macvlan profiles, 'BindsToInterfaces' contains the name of a
single network interface.

All options for connections of the `ethernet' type are understood for
connections of the `macvlan' type. Next to the *ip options*, the
following are understood for connections of the `macvlan' type:

'Mode='::
    Either `bridge', `vepa', `private', or `passthru'. See *ip*(8) for
    details.

'MACAddress='::
    Optional static MAC address for the `macvlan' type link.


SPECIAL QUOTING RULES
---------------------
Configuration files for *wpa_supplicant* use non-standard quoting.
Therefore, non-standard quoting rules exist for some variables for
connections of the `wireless' type. In particular, these variables are
'ESSID', and 'Key'.

A variable is considered *quoted* by *wpa_supplicant* if it is enclosed
in double quotes ("). A variable is considered *non-quoted* by
*wpa_supplicant* if it does not start with a double quote. Hexadecimal
values are specified *non-quoted* in configuration files of
*wpa_supplicant*. In *netctl*, variables are written to *wpa_supplicant*
configuration files *quoted* by default. When special quoting rules
apply, it is possible to specify an unquoted (hexadecimal) value using a
special syntax.

The special quoting rules of *netctl* are as follows. A string that
starts with a literal double quote is considered *non-quoted*. Any other
string is considered *quoted*. It is possible to specify quoted strings
that start with a double quote by quoting manually. An extreme example
is the specification of a *quoted* double quote: '`X='""""'`'. On the
other end of the spectrum there is the *non-quoted* backslash:
'`X=\"\\`'.

Further examples of *quoted* strings (all equivalent):
-------------
X=string
X="string"
X='""string"'
-------------

Further examples of *non-quoted* strings (all equivalent):
------------
X=\"string
X="\"string"
X='"string'
------------

A mnemonic is to think of the prefix ``\"`' as saying `non'-`quote'.


SEE ALSO
--------
*netctl*(1), *resolvconf.conf*(5)