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 .service or .conf. 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. 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
    Network bonding. This connection type requires ifenslave to be available.

bridge
    Network bridging. This connection type requires brctl to be available.

pppoe
    For PPPoE connections.

tunnel
    For tunnel interfaces.

tuntap
    For TUN/TAP interfaces.

vlan
    For VLANs 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 after a connection is brought down. Similar precautions should be taken as with ExecUpPost.

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]
    An array of IPv6 addresses. Prefix length may be specified via ‘1234:bcd::11/64’ syntax.

Gateway6= [requires IP6=static]
    An IPv6 routing gateway address.

Routes6=
    An array of custom routes of the form ‘<address range> via <gateway>’.

DHCPClient= [requires a DHCP setting]
    The name of the preferred DHCP client. Supported options are ‘dhcpcd’ and ‘dhclient’. Defaults to ‘dhcpcd’.

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.

DNSSearch=
    A ‘search’ line for /etc/resolv.conf.

DNSOptions=()
    An array of ‘options’ lines for /etc/resolv.conf.

TimeoutDHCP=
    Maximum time, in seconds, to wait for DHCP to be successful. Defaults to ‘10’.

TimeoutDAD=
    Maximum time, in seconds, to wait for IPv6’s Duplicate Address Detection to succeed. Defaults to ‘3’.

OPTIONS FOR ‘ETHERNET’ CONNECTIONS

Next to the ip options, the following are understood for connections of the ‘ethernet’ type:

SkipNoCarrier=
    Whether or not the absence of a carrier (plugged-in cable) is acceptable. Defaults to ‘no’.

Auth8021X=
    Set to ‘yes’ to use 802.11x authentication.

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

WPADriver=
    The wpa_supplicant driver to use for 802.11x 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.11x authentication to succeed. Defaults to ‘15’.

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’.

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

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’.

ExcludeAuto=
    Whether or not to exclude this profile from automatic profile selection. Defaults to ‘no’.

WPAGroup=
    Group that has the authority to configure wpa_supplicant via its control interface. Defaults to ‘wheel’.

WPAConfigSection=() [mandatory for Security=wpa-configsection]
    Array of lines that form a network block for wpa_supplicant.

WPAConfigFile=
    Path to a wpa_supplicant configuration file. Defaults to /etc/wpa_supplicant.conf. Used for Security=wpa-config.

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. 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 are understood for connections of the ‘bridge’ type:

FwdDelay=
    Forward delay of the bridge. See brctl(8) for details.

MaxAge=
    Maximum age parameter. See brctl(8) for details.

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 can set a vlan identifier using VLANID=. See ip(8) for details.

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)