summaryrefslogtreecommitdiffstats
path: root/docs/netcfg-profiles.txt
blob: c519e43542bf056c603fbbb0b0c6ded25be24160 (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
% NETCFG-PROFILES(5) netcfg 2.6.6 | Arch Linux
% Rémy Oudompheng <remy@archlinux.org>
  James Rayner <james@archlinux.org>
% 30 July 2011

NAME
====

netcfg-profiles -- netcfg profiles documentation and syntax

DESCRIPTION
===========

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

They are named */etc/network.d/${profile_name}*.

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 behaviour.
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.
bridge
:   Network bridge setup using **brctl**(8).
tuntap
:   TUN/TAP interfaces.
vlan
:   VLAN setup.
openvpn
:   OpenVPN setup.
ppp
:   PPP 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)
:   Can be either 'static' or 'dhcp'.  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. For example:
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*)
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.
IFOPTS (deprecated, requires IP of 'static')
:   Arguments to pass to 'ifconfig'. This allows you to use the syntax
    for the older 'ifconfig' tool. Retained for compatability.
## IPv6 options
IP6 (required for IPv6)
:   Either 'dhcp', 'dhcp-noaddr', 'stateless', 'static'. Leave unset to disable IPv6.
ADDR6 (required for IP6=static)
:   An array of IPv6 addresses: prefix length may be specified via '1234:bcd::11/64' syntax.
GATEWAY6 (for IP6=static)
:   The gateway address for IPv6 routing.
ROUTES6
:   An array of custom routes (of the form *address range* via *gateway*)
### DNS configuration
DNS
:   Array of DNS nameservers. Simply specify the IP's of each of the DNS nameservers.
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.
DNS1, DNS2 (deprecated)
:   First and second DNS servers for /etc/resolv.conf
### 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'.

## 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.
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.
IWCONFIG (optional, deprecated)
:   Run iwconfig with these options before attempting to configure the connection.

### 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 '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.