path: root/docs/netctl.profile.5.txt

NETCTL.PROFILE(5)
=================

NAME
----
netctl.profile - Profile options


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


DESCRIPTION
-----------
Profiles for netctl live under '/etc/network.d/' 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/network.d/hooks/' and
any executable script in '/etc/network.d/interfaces/' with the name of
the interface for the profile are sourced. For each connection type,
there are example profile files in '/etc/network.d/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, optionally suffixed with ``/<netmask>`',
    where netmask is an integer between 0 and 255. The default netmask
    is 24. 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)