NETCTL.PROFILE(5)

📦
version 1.29 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 NETCTL.PROFILE — the manual page, bestie edition (5) 💖

okay so you're here for netctl.profile(5)?? the profile options page?? iconic. let's go. this is part 1 of 3, so hydrate and stay with me 🫶

✨ NAME ✨

netctl.profile — profile options. that's it, that's the name. short king energy. 👑

🌸 SYNOPSIS 🌸

netctl.profile

💅 DESCRIPTION 💅

so. profiles for netctl live under /etc/netctl/ and they're literally just plain text files, no cap. they're made of variable definitions that follow bash shell syntax, and ngl they are not expected to execute any code — this is a vibe situation, not a script situation. the move is to omit as much quoting as humanly possible. however, for a few WPA-related variables, special quoting rules apply (they're below, keep reading, don't scroll past me 🙈).

the name of the profile is the name of the file. simple. elegant. and bestie, listen: profile names must not contain newlines, and should not end in .action, .conf, or .service. that's the rule. no exceptions, fr fr.

so whenever a profile is read, all the executable scripts in /etc/netctl/hooks/ get sourced, PLUS any executable script in /etc/netctl/interfaces/ that has the name of the interface for the profile. sneak peek behaviour, we love her ✨

  • 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

and the hierarchy?? the tea: declarations in an interface script override declarations in a profile, which override declarations in hooks. that's the order. respect it.

also every connection type has example profile files chillin' in /etc/netctl/examples/ — go look, they're free 💖

🌈 AVAILABLE CONNECTION TYPES 🌈

pick your fighter:

  • ethernet — for wired connections. the classic. the OG. 🔌
  • wireless — for wireless connections. this one requires wpa_supplicant to be available, so don't come crying if it's not installed 😭
  • bond — for bonded interfaces.
  • bridge — for bridge interfaces.
  • dummy — for dummy interfaces.
  • ppp — for PPP connections (currently only PPPoE, that's the limit bestie).
  • 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 🎀

these are the universal girlies, everyone gets them:

  • Description= — a description of the profile. basically a little bio. make it cute. 💅
  • Connection= — [mandatory for all profiles] the connection type used by the profile. required, babes, no skipping.
  • Interface= — [mandatory for all profiles] the name of the associated network interface. ⚠️ the interface name should not be quoted — just say the name, raw, unquoted, unbothered.
  • BindsToInterfaces=() — an array of physical network interfaces that this profile needs before it can be started. for 'enabled' profiles, systemd will literally wait for the presence of the specified interfaces before starting a profile. if you don't specify this variable, it defaults to the value of Interface=. she's self-sufficient like that.
  • 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. that's the whole list, don't @ me.
  • After=() — an array of profile names that should be started before this profile is started. careful though: this is only an ordering dependency, it is not intended to be a list of profiles that this profile requires. the meaning is the same as After= in systemd.unit(5). it's giving "after you, no after YOU" 🦋
  • 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 you want the command to be allowed to fail, add || true to the end of it. chaos-proof it 💀
  • ExecDownPre= — a command that is executed before a connection is brought down. similar precautions should be taken as with ExecUpPost=. same energy, different direction.
  • 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. i'm serious. this is not a vibe-check situation, this is a "you better know what you're doing" situation.
  • 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. turn it on when things are cursed 🔥

🧚 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. so basically the whole squad.

  • 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. and here's the subtle flex: the difference between not specifying and setting to no is in the handling of router advertisement packages, which is blocked by no. so no is not the same as nothing. write that down 📝
  • Address=() — [requires IP=static] an array of IP addresses suffixed with /<netmask>. leaving out the brackets for arrays consisting of a single element is accepted in the Bash syntax. we're being lenient, we're being nice 🫶
  • 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 the 1234:bcd::11/64 syntax. and yes you can specify modifiers — in particular, 1234:bcd::11/64 nodad disables Duplicate Address Detection for the address. fancy ✨
  • 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), and 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=, and command line options for the IPv6 instance of dhclient(8) are read from DhclientOptions6=. defaults to dhclient. yes, the v6 default is different from the v4 default. she contains multitudes 💜
  • DHCPReleaseOnStop= — set to yes to release the DHCP lease when the profile is stopped. let it go, girl 🌸
  • IPCustom=() — an array of argument lines to pass to ip. this can be used to achieve complicated configurations within the framework of netctl. for the overachievers.
  • Hostname= — a transient hostname for the system. a little name tag, but temporary.
  • DNS=() — an array of DNS nameservers. simply specify the IP addresses of each of the DNS nameservers. no extra steps, babes.
  • 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. be patient with her 😭
  • 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 (yeah, all of those up there still apply), 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 (a plugged-in cable, bestie, an actual 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. so yeah, higher number = tried first. main character energy 👑

okay that's the first chunk!! there are more parts coming, so do NOT close the tab, we're not done yet 💖

💖 OPTIONS FOR ‘WIRELESS’ CONNECTIONS 💖

okay bestie, so besides all the ip options you already learned, wireless connections also understand the stuff below. wifi girlies rise 🦋✨

  • Security= — one of ‘none’, ‘wep’, ‘wpa’, ‘wpa-configsection’, or ‘wpa-config’. Defaults to ‘none’. pick your fighter 💅
  • ESSID= [mandatory] — the name of the network you're connecting to. Special quoting rules apply (they're explained somewhere below, iykyk). yes it's mandatory, no you can't skip it 🙈
  • AP= — the BSSID (that's a MAC address, bestie) of the access point you want to connect to.
  • Key= — the secret key to a WEP or WPA encrypted network. Special quoting rules apply here too 🔐
  • Hidden= — whether or not the network you specified 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, obviously) to scan when searching for the network. Defaults to all available frequencies. it's giving "scan everything" energy ✨
  • Frequency= — a frequency in MHz to use in ad-hoc mode when a new IBSS is created (aka when the network isn't already there).
  • Priority= — priority group for the network. When automatic profile selection happens, the matched network with the highest priority wins. Defaults to ‘0’. main character network only 👑
  • WPAConfigSection=() [mandatory for Security=wpa-configsection] — an array of lines that make up a network block for wpa_supplicant. Heads up: all of the options above get ignored. all of them. 💀
  • WPAConfigFile= — path to a wpa_supplicant configuration file. Only used for Security=wpa-config. Every option except WPADriver=, TimeoutWPA=, and RFKill= gets ignored. Also, 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= — the 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= — the maximum time, in seconds, to wait for steps in the association and authentication to succeed. Defaults to ‘15’. tick tock ⏰
  • RFKill= — the name of an rfkill device. When you specify one, that device gets used to block/unblock the interface when appropriate. You can find names in /sys/class/rfkill/rfkillX/name. You can also set this variable to ‘auto’ — in that case, an rfkill device that's associated with the network interface gets used. so convenient fr fr

🔥 OPTIONS FOR ‘BOND’ CONNECTIONS 🔥

the interfaces listed in BindsToInterfaces= get bound together into the interface named by Interface=. Next to the ip options, here's what bond connections understand:

  • Mode= — the bonding policy. Go read the kernel documentation on bonding for the deets.
  • LinkOptions= — extra options to pass to ip link. Run ip link add type bond help to see what's available.

🌈 OPTIONS FOR ‘BRIDGE’ CONNECTIONS 🌈

the interfaces in BindsToInterfaces= take part in the bridge named by Interface=. Next to the ip options, bridge connections understand this:

  • SkipForwardingDelay= — skip (R)STP and immediately activate all bridge members. This can be useful when DHCP is used on the bridge. no waiting, we go now 💨

🎀 OPTIONS FOR ‘DUMMY’ CONNECTIONS 🎀

the name of the dummy interface goes in Interface=. Only the ip options are understood for connections of the ‘dummy’ type. that's it, that's the whole section, lowkey iconic for how simple it is ✨

💜 OPTIONS FOR ‘PPP’ CONNECTIONS 💜

this connection type is literally identical to the ‘pppoe’ type below, except the ethernet interface gets specified in BindsToInterfaces=. Also, the value of Interface= has to be of the form ‘ppp<n>’, where n gets passed on to PPPUnit=.

🫶 OPTIONS FOR ‘PPPOE’ CONNECTIONS 🫶

the interface to dial peer-to-peer over ethernet goes in Interface=. Here's what ‘pppoe’ connections understand:

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

and the following advanced options are understood too, bestie, don't skip these:

  • 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 goes in Interface=. Here's what ‘mobile_ppp’ connections understand:

  • User= and Password= — the username and password to connect with. These are unset by default, because they're often not required. nice.
  • AccessPointName= — the access point name (APN) to present to the carrier. This one's specific to your ISP, so yeah, you gotta know it.
  • 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’. don't be out here setting Huawei stuff on your not-Huawei modem, bestie, that's a whole vibe check fail 💀
  • Init= — an initialization string sent to the modem before dialing. This string gets sent after sending “ATZ”. Defaults to ‘ATQ0 V1 E1 S0=0 &C1 &D2 +FCLASS=0’.
  • ChatScript= — path to a chat file. If you specify one, no chat script will be generated and all of the options above except User= and Password= get 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 gets used to block/unblock the interface when appropriate. You can find names in /sys/class/rfkill/rfkillX/name. (no ‘auto’ here, just so you know — that was the wireless one 🫶)

⭐ OPTIONS FOR ‘OPENVSWITCH’ CONNECTIONS ⭐

the interfaces in BindsToInterfaces= take part in the bridge named by Interface=. Only the ip options are understood for connections of the ‘openvswitch’ type. short and sweet ✨

🌸 OPTIONS FOR ‘TUNNEL’ CONNECTIONS 🌸

the name of the tunnel interface goes in Interface=. Next to the ip options, ‘tunnel’ connections understand:

  • Mode= — the tunnel type (e.g. ‘sit’). See ip-tunnel(8) for the 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 goes in Interface=. Next to the ip options, ‘tuntap’ connections understand:

  • 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 goes in Interface=. The underlying physical interface goes in BindsToInterfaces=. So for vlan profiles, BindsToInterfaces= holds the name of a single network interface — just one, no plural shenanigans.

All the options for connections of the ‘ethernet’ type are understood for connections of the ‘vlan’ type. On top of that, ‘vlan’ connections must set a vlan identifier using VLANID=. See ip(8) for details. mandatory, fr fr 💅

🧚 OPTIONS FOR ‘MACVLAN’ CONNECTIONS 🧚

the name of the macvlan interface goes in Interface=. The underlying physical interface goes in BindsToInterfaces=. So for macvlan profiles, BindsToInterfaces= holds the name of a single network interface, same deal as vlan.

All the options for connections of the ‘ethernet’ type are understood for connections of the ‘macvlan’ type. And next to the ip options, ‘macvlan’ connections also understand:

  • Mode= — either ‘bridge’, ‘vepa’, ‘private’, or ‘passthru’. See ip(8) for details.

💫 OPTIONS FOR ‘WIREGUARD’ CONNECTIONS 💫

the name of the WireGuard interface goes in Interface=. Next to the ip options, ‘wireguard’ connections understand one iconic little thing:

  • WGConfigFile= — path to a WireGuard configuration file. Defaults to /etc/wireguard/$Interface.conf.

and that's where this part wraps… except it doesn't, because there's more coming 💖

✨ SPECIAL QUOTING RULES ✨

okay bestie, buckle up because this is the ✨weird✨ part. wpa_supplicant config files use non-standard quoting — like, they did NOT follow the normal rules, they chose chaos 💀 — and because we're out here generating those files for you, netctl has to have its own lil quoting rules too. These apply to some variables for connections of the ‘wireless’ type. Specifically? These two, bestie:

  • ESSID=
  • Key=

so yeah, just those. 💅

Here's the tea on how wpa_supplicant itself thinks about this:

  • A variable counts as quoted by wpa_supplicant if it's enclosed in double quotes ("). 🎀
  • A variable counts as non-quoted by wpa_supplicant if it does ✨not✨ start with a double quote.
  • Hexadecimal values are specified non-quoted in config files of wpa_supplicant.

But netctl does it differently by default: in netctl, variables are written to wpa_supplicant configuration files quoted by default. And so, when special quoting rules apply, it is possible to specify an unquoted (hexadecimal) value using a special syntax. iconic, honestly 🫶

So what ARE netctl's special quoting rules? say it with me:

  • A string that starts with a literal double quote is considered non-quoted.
  • Any other string is considered quoted. periodt.

And yeah, you can specify quoted strings that start with a double quote — you just have to quote manually, bestie. ✨

The most unhinged example, the extreme one: specifying a quoted double quote:

X='""""'

😭 she's a menace. And on the total opposite end of the spectrum, there's the non-quoted backslash:

X=\"\\

Further examples of quoted strings — all equivalent, no cap:

X=string
X="string"
X='""string"'

Further examples of non-quoted strings — also all equivalent:

X=\"string
X="\"string"
X='"string'

And here's the mnemonic to remember all of this 🧚: think of the prefix ‘\"’ as saying ‘non’-‘quote’. that's it. that's the trick. iykyk 💜

🌈 SEE ALSO 🌈

and that's the whole page bestie, you made it to the end 🥳 this one's from the netctl.profile(5) era, dated 01/26/2026 — go forth and configure your little heart out, you absolute main character 👑💖

📦 where this page comes from