Identifying devices of an Instance
An Instance is composed of a multitude of devices. Some of them can be configured, such as network interfaces and block devices, for example by attaching an SBS volume to the Instance or attaching the Instance to a Private Network.
On a Linux host, devices are named by the kernel in the order they are discovered. The order in which devices are discovered is dependent on things such as the topology of the PCI hierarchy which are not guaranteed to be stable across poweroff/poweron/reboot actions.
This guide aims to provide tips to help you identify devices in a stable manner on a Linux host.
Identifying Instance block storage volumes (b_ssd)
Instance block storage (b_ssd) volumes are connected to the Instance as SCSI disks. They will therefore appear as devices handled by the sd driver in the dev filesystem, i.e. as /dev/sd{a,b,c...} devices.
SCSI disks have multiple attributes, such as vendor and product/model. They also have a serial. Instance block storage (b_ssd) volumes have the vendor name SCW, the model/product name b_ssd, and a serial set to volume-<uuid> where <uuid> is the ID of the volume.
The lsblk can be used to list SCSI devices and will show these attributes:
Through udev and the sets of configured udev rules, these attributes will be retrieved and symlinks will be automatically created for the /dev/sdX devices. As the attributes are stable, these symlinks provide a stable path to the devices, as long as the udev rule does not change.
For example, at the time of writing, the 60-persistent-storage.rules ruleset shipped with systemd on most distributions contains rules which will create symlinks under /dev/disk/by-id/. Specifically of interest are the following rules:
In the first rule, the sdX kernel name is matched, and the scsi_id command is executed. Its output will be imported into the udev environment for the following rules. Let’s see what the command outputs:
The third and fourth rules create the symlinks proper, using these attributes. This will result in the following symlinks being created:
In this setup, we can see an entry named after the f7a6f113-aaf6-4540-ac5a-9e18d7f61478 volume, pointing to the /dev/sda device node, along with three entries also created automatically which point to the individual partitions on the volume.
Note that these rulesets are shipped by the distributions and are out of the control of Scaleway. Their stability is not guaranteed.
Though symlinks are created based on rules which are packaged by distributions, it is also possible to create your own rules to fit your preferred naming. For example, if we create a rule such as:
This rule will create a symlink /dev/disk/scw/volume-<uuid> (where uuid is the ID of the volume) for each volume:
Note that this rule relies on ID_VENDOR and ID_SERIAL_SHORT being in the environment, and thus relies on the execution of scsi_id and the importing of its output.
For more details on writing udev rules, please see man 7 udev.
Identifying VPC Private Network interfaces
VPC Private Networks to which the Instance is connected will appear as virtio PCI network devices, handled by the virtio-net driver.
As all PCI devices, they can be listed with the lspci command:
The filter selects the Network controller device class/Ethernet controller device subclass. Three PCI devices are visible, which correspond to the public network device, and two VPC Private Network devices. By itself, the output of this command is not enough to distinguish between public and private networks, and can not distinguish between multiple private networks either: this simply confirms their existence in the PCI hierarchy of the Instance.
More interestingly, network interfaces can be listed generically using the ip link show command:
Here, four interfaces are listed, one of which (lo) is the virtual loopback interface and can be disregarded. The three other correspond to the aforementioned public network interface, and VPC Private Network interfaces.
A simple and effective way to distinguish the public network interface from the VPC Private Network interfaces is the MAC address prefix. VPC Private Network interfaces always have a MAC address starting with 02:00:00.
Using the JSON output mode of the ip command and filtering with the jq JSON parser, we can thus list VPC Private Network interfaces:
Using the MAC address of the interfaces, it is also possible to distinguish between the different VPC Private Network interfaces. The MAC address of each interface is available through the API.
For example, querying /instances/v1/<zone>/servers/<uuid>/private_nics, where <zone> is the zone of the server and <uuid> is the ID of the Instance gives:
Two entries are listed, which correspond to the interfaces given by the output of ip link show above. The output contains the ID of the VPC Private Network, which helps distinguishing between the two.
Through the use of udev rules, it is possible to rename the interfaces if desired. For example, the following rule would assign the static name priv0 to the interface with MAC address 02:00:00:b7:c8:a5:
If a more complex scheme is desired, such as including part of the name of the corresponding VPC Private Network, the rule could instead be:
This rule would start the systemd service my-vpc-service@<ifname> when a new interface with name <ifname> is added and has a MAC address matching the VPC Private Network prefix.
The systemd service can then execute complex operations (retrieving the server’s private_nics informations, the VPC Private Network information through the VPC API, applying custom logic, etc.)