src/shared/netif-naming-scheme.h

   1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
   2 #pragma once
   3
   4 #include <stdbool.h>
   5
   6 #include "sd-device.h"
   7
   8 #include "macro.h"
   9
  10 /* So here's the deal: net_id is supposed to be an exercise in providing stable names for network devices. However, we
  11  * also want to keep updating the naming scheme used in future versions of net_id. These two goals of course are
  12  * contradictory: on one hand we want things to not change and on the other hand we want them to improve. Our way out
  13  * of this dilemma is to introduce the "naming scheme" concept: each time we improve the naming logic we define a new
  14  * flag for it. Then, we keep a list of schemes, each identified by a name associated with the flags it implements. Via
  15  * a kernel command line and environment variable we then allow the user to pick the scheme they want us to follow:
  16  * installers could "freeze" the used scheme at the moment of installation this way.
  17  *
  18  * Developers: each time you tweak the naming logic here, define a new flag below, and condition the tweak with
  19  * it. Each time we do a release we'll then add a new scheme entry and include all newly defined flags.
  20  *
  21  * Note that this is only half a solution to the problem though: not only udev/net_id gets updated all the time, the
  22  * kernel gets too. And thus a kernel that previously didn't expose some sysfs attribute we look for might eventually
  23  * do, and thus affect our naming scheme too. Thus, enforcing a naming scheme will make interfacing more stable across
  24  * OS versions, but not fully stabilize them. */
  25 typedef enum NamingSchemeFlags {
  26         /* First, the individual features */
  27         NAMING_SR_IOV_V                  = 1 << 0, /* Use "v" suffix for SR-IOV, see 609948c7043a */
  28         NAMING_NPAR_ARI                  = 1 << 1, /* Use NPAR "ARI", see 6bc04997b6ea */
  29         NAMING_INFINIBAND                = 1 << 2, /* Use "ib" prefix for infiniband, see 938d30aa98df */
  30         NAMING_ZERO_ACPI_INDEX           = 1 << 3, /* Use zero acpi_index field, see d81186ef4f6a */
  31         NAMING_ALLOW_RERENAMES           = 1 << 4, /* Allow re-renaming of devices, see #9006 */
  32         NAMING_STABLE_VIRTUAL_MACS       = 1 << 5, /* Use device name to generate MAC, see 6d3646406560 */
  33         NAMING_NETDEVSIM                 = 1 << 6, /* Generate names for netdevsim devices, see eaa9d507d855 */
  34         NAMING_LABEL_NOPREFIX            = 1 << 7, /* Don't prepend ID_NET_LABEL_ONBOARD with interface type prefix */
  35         NAMING_NSPAWN_LONG_HASH          = 1 << 8, /* Shorten nspawn interfaces by including 24bit hash, instead of simple truncation  */
  36         NAMING_BRIDGE_NO_SLOT            = 1 << 9, /* Don't use PCI hotplug slot information if the corresponding device is a PCI bridge */
  37         NAMING_SLOT_FUNCTION_ID          = 1 << 10, /* Use function_id if present to identify PCI hotplug slots */
  38         NAMING_16BIT_INDEX               = 1 << 11, /* Allow full 16-bit for the onboard index */
  39         NAMING_REPLACE_STRICTLY          = 1 << 12, /* Use udev_replace_ifname() for NAME= rule */
  40         NAMING_XEN_VIF                   = 1 << 13, /* Generate names for Xen netfront devices */
  41         NAMING_BRIDGE_MULTIFUNCTION_SLOT = 1 << 14, /* Use PCI hotplug slot information associated with bridge, but only if PCI device is multifunction.
  42                                                      * This is disabled since v255, as it seems not to work at least for some setups. See issue #28929. */
  43         NAMING_DEVICETREE_ALIASES        = 1 << 15, /* Generate names from devicetree aliases */
  44         NAMING_USB_HOST                  = 1 << 16, /* Generate names for usb host */
  45         NAMING_SR_IOV_R                  = 1 << 17, /* Use "r" suffix for SR-IOV VF representors */
  46
  47         /* And now the masks that combine the features above */
  48         NAMING_V238 = 0,
  49         NAMING_V239 = NAMING_V238 | NAMING_SR_IOV_V | NAMING_NPAR_ARI,
  50         NAMING_V240 = NAMING_V239 | NAMING_INFINIBAND | NAMING_ZERO_ACPI_INDEX | NAMING_ALLOW_RERENAMES,
  51         NAMING_V241 = NAMING_V240 | NAMING_STABLE_VIRTUAL_MACS,
  52         NAMING_V243 = NAMING_V241 | NAMING_NETDEVSIM | NAMING_LABEL_NOPREFIX,
  53         NAMING_V245 = NAMING_V243 | NAMING_NSPAWN_LONG_HASH,
  54         NAMING_V247 = NAMING_V245 | NAMING_BRIDGE_NO_SLOT,
  55         NAMING_V249 = NAMING_V247 | NAMING_SLOT_FUNCTION_ID | NAMING_16BIT_INDEX | NAMING_REPLACE_STRICTLY,
  56         NAMING_V250 = NAMING_V249 | NAMING_XEN_VIF,
  57         NAMING_V251 = NAMING_V250 | NAMING_BRIDGE_MULTIFUNCTION_SLOT,
  58         NAMING_V252 = NAMING_V251 | NAMING_DEVICETREE_ALIASES,
  59         NAMING_V253 = NAMING_V252 | NAMING_USB_HOST,
  60         NAMING_V254 = NAMING_V253 | NAMING_SR_IOV_R,  /* Despite the name, "v254" is NOT the default scheme
  61                                                        * for systemd version 254. It was added in a follow-up
  62                                                        * patch later. NAMING_SR_IOV_R is enabled by default in
  63                                                        * systemd version 255, naming scheme "v255". */
  64         NAMING_V255 = NAMING_V254 & ~NAMING_BRIDGE_MULTIFUNCTION_SLOT,
  65
  66         EXTRA_NET_NAMING_SCHEMES
  67
  68         _NAMING_SCHEME_FLAGS_INVALID = -EINVAL,
  69 } NamingSchemeFlags;
  70
  71 typedef struct NamingScheme {
  72         const char *name;
  73         NamingSchemeFlags flags;
  74 } NamingScheme;
  75
  76 const NamingScheme* naming_scheme_from_name(const char *name);
  77 const NamingScheme* naming_scheme(void);
  78
  79 static inline bool naming_scheme_has(NamingSchemeFlags flags) {
  80         return FLAGS_SET(naming_scheme()->flags, flags);
  81 }
  82
  83 typedef enum NamePolicy {
  84         NAMEPOLICY_KERNEL,
  85         NAMEPOLICY_KEEP,
  86         NAMEPOLICY_DATABASE,
  87         NAMEPOLICY_ONBOARD,
  88         NAMEPOLICY_SLOT,
  89         NAMEPOLICY_PATH,
  90         NAMEPOLICY_MAC,
  91         _NAMEPOLICY_MAX,
  92         _NAMEPOLICY_INVALID = -EINVAL,
  93 } NamePolicy;
  94
  95 const char *name_policy_to_string(NamePolicy p) _const_;
  96 NamePolicy name_policy_from_string(const char *p) _pure_;
  97
  98 const char *alternative_names_policy_to_string(NamePolicy p) _const_;
  99 NamePolicy alternative_names_policy_from_string(const char *p) _pure_;
 100
 101 int device_get_sysattr_int_filtered(sd_device *device, const char *sysattr, int *ret_value);
 102 int device_get_sysattr_unsigned_filtered(sd_device *device, const char *sysattr, unsigned *ret_value);
 103 int device_get_sysattr_bool_filtered(sd_device *device, const char *sysattr);
 104 int device_get_sysattr_value_filtered(sd_device *device, const char *sysattr, const char **ret_value);