ethxlattopology(8)

💖 ethxlattopology — bestie's guide to building your cluster topology ✨

okay so this is ethxlattopology(8), part of the EFSFFCLIRG man pages, and it is literally the tool that makes your cluster's topology XML file exist. no cap.

---

🌸 NAME 🌸

ethxlattopology — generates a topology XML file of a cluster using your customized <topologyfile>.csv and core switch linksum files (like linksum_swd06.csv and linksum_swd24.csv, iykyk) as input. that output topology XML file can then be used to bring up and verify the cluster. iconic behavior fr fr 💅

---

✨ Syntax ✨

ethxlattopology [-d  level] [-v  level] [-i  level] [-K] [-N] [-f linkfiles]

[-o  report] [-p  plane] [source [dest]]

---

🎀 Options 🎀

• --help — produces the full help text. your little safety net bestie 🫶
• -d level — sets the output detail level. default is 0. the levels are additive, so they stack 💫

by default, the top level is always produced. switch, rack, and rack group topology files can be added to the output by choosing the appropriate level. if you ask for output at the group or rack level, then group or rack names must be provided in the spreadsheet (no names = no vibes, sorry 😭). detailed output can be specified in any combination. a directory for each topology XML file is created hierarchically, with group directories (if specified) at the highest level, followed by rack and switch directories (if specified).

1. core switch topology files.
2. rack topology files.
4. rack group topology files.

• -v level — sets the verbose level. range is 0 - 8. default is 2. levels are additive too ✨
  0. no output.
  1. progress output.
  2. reserved.
  4. time stamps.
  8. reserved.
• -i level — sets the output indent level. default is 4. pretty formatting, we love to see it 💅
• -K — specifies DO NOT clean temporary files.

this prevents temporary files in each topology directory from being removed. those temporary files contain CSV formatted lists of links, NICs, and switches used to create a topology XML file. ngl, temporary files are not typically needed after a topology file is created — but they can be retained for subsequent inspection or processing if you're nosy like me 🙈

• -N — specifies DO NOT generate Port Numbers from Port IDs.

heads up: this will introduce slightly poorer topology-loading performance. it's useful when it's difficult to generate Port Numbers, like with complicated Port ID formats, or when there aren't enough Port IDs to train the Port Number generator. lowkey a struggle but it's there for you 💜

• -f linkfiles — specifies the space separated core switch linksum files.
• -o report — specifies the report type for output. by default, all the sections are generated.

Report Types:

• brnodes — creates the <Node> section xml for the csv input.
• links — creates the <LinkSummary> section xml for the csv input.

• -p plane — specifies the plane name. default is plane.
• source — specifies the source csv file. default is topology.csv.
• dest — specifies the output xml file. default is topology.xml.

the default output file name can be used to specify the destination folder. cute little trick, iykyk 🧚

---

🦋 Description 🦋

the ethxlattopology script reads your customized <topologyfile>.csv file from the local directory, and reads the core switch linksum files specified by the -f argument. there are two sample topology XLSX files, detailed_topology.xlsx and minimal_topology.xlsx, chillin' in the /usr/share/eth-tools/samples/ directory.

you must create your <topologyfile>.csv file by editing one of the sample spreadsheets and saving the Fabric Links tab as a CSV file. then — and this part matters bestie — inspect your <topologyfile>.csv file to make sure that each row contains the correct and same number of comma separators. any extraneous entries in the spreadsheet can cause the CSV output to have extra fields 😭 and that's a whole mess. do the same thing on the "Internal xxx Links" tab to create your own internal core switch linksum csv files.

---

🌈 Example 🌈

ethxlattopology -f "/usr/share/eth-tools/samples/linksum_swd06.csv
/usr/share/eth-tools/samples/linksum_swd24.csv"
/tmp/detailed_topology.csv

and then it prints all of this:

Parsing linksum file: /usr/share/eth-tools/samples/linksum_swd06.csv

Parsing linksum file: /usr/share/eth-tools/samples/linksum_swd24.csv

Parsing /tmp/detailed_topology.csv

Generating links for Core:core1

Generating links for Core:core2

Processing Leaves of partially populated Core:core2

Processing spines of partially populated Core:core2

Generating topology.xml file(s)

Done

both sample files contain examples of links between NIC and Edge SW (rows 4-7), NIC and Core SW (rows 8-11), and Edge SW and Core SW (rows 12-15). ate that 💖

---

💜 Environment Variables 💜

the following environment variables allow user-specified MTU.

• MTU_SW_SW — if set, it overrides default MTU on switch-to-switch links. default is 10240.
• MTU_SW_NIC — if set, it overrides default MTU on switch-to-NIC links. default is 10240.

---

👑 Multi-Rail and Multi-Plane Fabrics 👑

for Multi-Rail/Multi-Plane fabrics, you have the following options:

• for Multi-Rail fabrics or for a Single Plane fabric with some multi-ported hosts, you can create multiple rows for a host with different Port names, and then follow the standard procedure to generate <topologyfile>.xml.
• for a Multi-Plane fabric with identical planes, the tool can be run multiple times on the same <topologyfile>.csv modified with different port names. for example, if there are two identical fabrics (fabric_1 and fabric_2) connected to a single host with two NICs (eth2 and eth3), the tool can be run twice like this:
• for fabric_1:

in <topologyfile>.csv, set port name to be eth2 for hosts.

• for fabric_2:

in <topologyfile>.csv, set port name to be eth3 for hosts.

• for a fabric with both Multi-Rail and Multi-Plane segments, you can use a combination of the above techniques to generate the desired <topologyfile>.xml file.

---

ngl the whole thing is giving "trust the process" energy, but once that topology.xml lands you're gonna feel like the main character 💅✨

okay bestie that's the whole page — this was ethxlattopology(8) from the EFSFFCLIRG man pages, copyright Copyright(C) 2020-2024 Intel Corporation, and that's the vibe check, periodt 🎀🦋💖