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

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.

       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.

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

       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.

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

       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 ‘systemd-network’.

       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.

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)

                                            05/27/2024                          NETCTL.PROFILE(5)