netctl.profile - Profile options
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. The name of the current profile is available via the
Profile variable in the environment of the sourced scripts. On
starting or stopping a profile, the respective command is available via the
Command variable. 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/.
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.
openvswitch
For Open vSwitch bridge interfaces.
tunnel
For tunnel interfaces.
tuntap
For TUN/TAP interfaces.
vlan
For VLANs on ethernet-like connections.
macvlan
For MACVLANs on ethernet-like connections.
wireguard
For WireGuard interfaces.
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=.
MACAddress=
Optional MAC address for newly created interfaces. When
set to the name of an existing interface, the address of that interface is
used. The connection types that create an interface and are able to set a MAC
address are bond, bridge, dummy, vlan, and macvlan.
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).
WaitOnline=
Set to ‘yes’ to consider the profile
activated only when it is online. Defaults to ‘no’.
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.
ExcludeAuto=
Whether or not to exclude this profile from automatic
profile selection. Defaults to ‘no’ for wireless and DHCP
enabled connections and to ‘yes’ otherwise.
NETCTL_DEBUG=
Set to ‘yes’ to generate debugging
output.
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. By default,
netctl comes with support for ‘dhcpcd’ and
‘dhclient’. Clients may accept additional options through
client-specific variables. Command line options for
dhcpcd(8) are read
from
DhcpcdOptions= (defaults to ‘-L’). Command line
options for
dhclient(8) are read from
DhclientOptions=. Defaults
to ‘dhcpcd’.
DHCP6Client= [requires IP6=dhcp or
IP6=dhcp-noaddr]
The name of the DHCPv6 client to use. By default,
‘dhcpcd’ and ‘dhclient’ are supported. Command
line options for the IPv6 instance of
dhcpcd(8) are read from
DhcpcdOptions6=. Command line options for the IPv6 instance of
dhclient(8) are read from
DhclientOptions6=. 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 transient hostname for the system.
DNS=()
An array of DNS nameservers. Simply specify the IP
addresses of each of the DNS nameservers.
DNSDomain=
DNSSearch=
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’.
Priority=
Priority level of the profile. In case of automatic
profile selection, profiles are tried in decreasing order of priority.
Defaults to ‘1’ in DHCP enabled profiles and to
‘0’ otherwise.
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.
Frequency=
A frequency in MHz to use in ad-hoc mode when a new IBSS
is created (i.e. the network is not already present).
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.
OPTIONS FOR ‘BOND’ CONNECTIONS
The interfaces of BindsToInterfaces= are bound together in
the interface named by Interface=. Next to the ip options, the
following is understood for connections of the ‘bond’
type:
Mode=
The bonding policy. See the kernel documentation on
bonding for details.
LinkOptions=
Additional options to be passed to ip link. Run
ip link add type bond help to see the available options.
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.
LinkOptions=
Additional options to be passed to ip link. Run
ip link add type bridge help to see the available options.
OPTIONS FOR ‘DUMMY’ CONNECTIONS
The name of the dummy interface is specified 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 to
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=
One of ‘persist’ or ‘demand’,
depending on how a connection should be established. Defaults to
‘persist’.
IdleTimeout= [requires ConnectionMode=demand]
The idle time (in seconds) after which the PPP daemon
should disconnect.
MaxFail=
The number of consecutive failed connection attempts to
tolerate. A value of 0 means no limit. Defaults to ‘5’.
DefaultRoute=
Whether or not to use the default route provided by the
peer. Defaults to ‘yes’.
UsePeerDNS=
Whether or not to use the DNS servers provided by the
peer. Defaults to ‘yes’.
PPPUnit=
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(8) options
from.
The following advanced options are also understood:
PPPoEService=
The PPPoE service name.
PPPoEAC=
The PPPoE access concentrator name.
PPPoESession=
An existing session to attach to. This option is of the
form ‘sessid:macaddr’.
PPPoEMAC=
A MAC address to restrict the connection to.
PPPoEIP6=
Whether or not to enable IPv6CP and IPv6 protocols. When
set to ‘no’, IPv6CP negotiation and IPv6 communication is
explicitly disabled.
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:
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 name (APN) to present to the carrier.
This is specific to your ISP.
Pin=
If your modem requires a PIN to unlock, set it
here.
PhoneNumber
The number to dial. Defaults to
‘*99#’.
Mode=
The connection mode. Can be one of
‘3Gpref’, ‘3Gonly’, ‘GPRSpref’,
‘GPRSonly’, ‘None’, or a custom AT^SYSCFG=... line
specified as ‘SYSCFG=...’. This generates AT commands specific
to certain Huawei modems; all other devices should leave this option unset or
set to ‘None’.
Init=
An initialization string sent to the modem before
dialing. This string is sent after sending “ATZ”. Defaults to
‘ATQ0 V1 E1 S0=0 &C1 &D2 +FCLASS=0’.
ChatScript=
Path to a chat file. If specified, no chat script will be
generated and all of the above options except User= and
Password= will be ignored.
MaxFail=
The number of consecutive failed connection attempts to
tolerate. A value of 0 means no limit. Defaults to ‘5’.
DefaultRoute=
Whether or not to use the default route provided by the
peer. Defaults to ‘yes’.
UsePeerDNS=
Whether or not to use the DNS servers provided by the
peer. Defaults to ‘yes’.
PPPUnit=
The PPP unit number in the interface name
(‘ppp0’, ‘ppp1’, etc.).
OptionsFile=
A file to read additional
pppd(8) options
from.
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.
OPTIONS FOR ‘OPENVSWITCH’ CONNECTIONS
The interfaces of BindsToInterfaces= take part in the
bridge named by Interface=. Only the ip options are understood
for connections of the ‘openvswitch’ type.
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-tunnel(8) for available modes.
Local=
The address of the local end of the tunnel.
Remote=
The address of the remote end of the tunnel.
Key= [requires Mode=gre]
A key identifying an individual traffic flow within a
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.
OPTIONS FOR ‘WIREGUARD’ CONNECTIONS
The name of the WireGuard interface is specified in
Interface=. Next to the ip options, the following are
understood for connections of the ‘wireguard’ type:
WGConfigFile=
Path to a WireGuard configuration file. Defaults
to /etc/wireguard/$Interface.conf.
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’.