IBPORTSTATE(8)

✨ IBPORTSTATE ✨

okay bestie, this is the ibportstate page from the Open IB Diagnostics fam — it lives in section 8 of the manual (the sysadmin-y one, iykyk) 💅

---

💖 NAME 💖

IBPORTSTATE — handle port (physical) state and link speed of an InfiniBand port 🦋

---

🌸 SYNOPSIS 🌸

ibportstate [options] <dest dr_path|lid|guid> <portnum> [<op>]

---

✨ DESCRIPTION ✨

so ibportstate is literally your girl for asking about the port state and port physical state of an IB port — that's the query part. and btw, when the port you're querying is a switch port, it also validates link width and speed against the peer port 👀

but it's not just a look-but-don't-touch situation. you can also use it to disable, enable, or reset a switch port. and here's the tea: an InfiniBand HCA port state can be changed locally without the Subnet Manager even knowing 😭 (no cap, it just doesn't know).

and if that wasn't enough, it also lets you adjust the link speed/width enabled on any IB port. versatile queen 👑

---

💅 OPTIONS 💅

🎀 <op> 🎀

Supported ops, in order, exactly as listed: enable, disable, reset, speed, espeed, fdr10, width, query, on, off, down, arm, active, vls, mtu, lid, smlid, lmc, mkey, mkeylease, mkeyprot.

Default op is query — if you don't pick one, that's what you get 🫶

now let's break the noteworthy ones down:

• enable, disable, and reset — change or reset a switch or HCA port state. ⚠️ psst: you must specify the CA name and Port number when locally changing CA port state.
• off — changes the port state to disable.
• on — changes the port state to enable, but only when the current state is disable. it's giving conditional queen.
• speed and width — allowed on any port 💖
• speed values — these are the legal values for PortInfo:LinkSpeedEnabled. if PortInfo:LinkSpeedSupported doesn't support the setting, you get an error. periodt.
• espeed — allowed on any port that supports extended link speeds.
• fdr10 — allowed on any port supporting fdr10. you get an error if the port's capability mask says extended link speeds aren't supported, or if PortInfo:LinkSpeedExtSupported doesn't support the setting.
• width values — legal values for PortInfo:LinkWidthEnabled. error if PortInfo:LinkWidthSupported doesn't support the setting.

🚨 NOTE: speed and width changes are not effected until the port goes through link renegotiation. so don't @ me when nothing changes instantly, bestie.

• query — also validates port characteristics (link width, speed, espeed, and fdr10) based on the peer port. this checking happens when the queried port is a switch port, because it relies on combined routing (an initial LID route with directed routing to the peer) — and that can only be done on a switch. and this whole peer port validation feature of the query op requires LID routing to be functioning in the subnet. 🔥
• mkey, mkeylease, and mkeyprot — only allowed on CAs, routers, or switch port 0. if you try it on external switch ports, you get an error, sorry babe 🙈
  • hexadecimal and octal mkeys: prepend the key with 0x or 0, respectively.
  • if you specify a non-numeric value (like 'x') for the mkey, ibportstate will prompt for a value. interactive icon ✨

---

🌈 Addressing Flags 🌈

• -L, --Lid — the address specified is a LID
• -G, --Guid — the address specified is a Port GUID
• -D, --Direct — the address specified is a directed route

Examples:

[options] -D [options] "0"          # self port
[options] -D [options] "0,1,2,1,4"  # out via port 1, then 2, ...

(Note: the second number in the path you specify must match the port being used. you can set that with the port selection flag -P, or let the automatic selection process find the port for you.)

• -s, --sm_port <smlid> — use 'smlid' as the target lid for SA queries.

---

🦋 Port Selection flags 🦋

• -C, --Ca <ca_name> — use the specified ca_name.
• -P, --Port <ca_port> — use the specified ca_port.
• -Y, --pkey-idx <idx> — P_Key table index (0-65535, default 0) used for the outgoing SA/GMP MADs. SMP (SMI directed-route/LID-routed) MADs always use P_Key index 0. no exceptions, bestie.

---

💜 Local port Selection 💜

Multiple port / Multiple CA support, hear me out: when no IB device or port is specified (see the "local umad parameters" below), the libibumad library picks the port using these criteria, in order:

1. the first port that is ACTIVE.
2. if not found, the first port that is UP (physical link up).

If a port and/or CA name is specified, libibumad tries to fulfill your request, and will simply fail if it can't. it's not gonna guess for you 💀

for example:

ibaddr                 # use the first port (criteria #1 above)
ibaddr -C mthca1       # pick the best port from "mthca1" only.
ibaddr -P 2            # use the second (active/up) port from the first available IB device.
ibaddr -C mthca0 -P 2  # use the specified port only.

---

🍓 Configuration flags 🍓

• --config, -z <config_file> — specify alternate config file. Default: /etc/infiniband-diags/ibdiag.conf
• -t, --timeout <timeout_ms> — override the default timeout for the solicited mads.
• -y, --m_key <key> — use the specified M_key for requests. if a non-numeric value (like 'x') is specified, then a value will be prompted for.

---

🧚 Debugging flags 🧚

• -h, --help — show the usage message
• -d — raise the IB debugging level. may be used several times (-ddd or -d -d -d).
• -e — show send and receive errors (timeouts and others)
• -K, --show_keys — show security keys (mkey, smkey, etc.) associated with the request. 🔐
• -v, --verbose — increase the application verbosity level. may be used several times (-vv or -v -v -v).
• -V, --version — show the version info.

---

🎀 FILES 🎀

💖 CONFIG FILE 💖

/etc/infiniband-diags/ibdiag.conf

A global config file is provided to set some of the common options for all tools. see the supplied config file for details, bestie 👑

---

🔥 EXAMPLES 🔥

ibportstate -C qib0 -P 1 3 1 disable     # by CA name, CA Port Number, lid, physical port number
ibportstate -C qib0 -P 1 3 1 enable      # by CA name, CA Port Number, lid, physical port number
ibportstate -D 0 1                       # (query) by direct route
ibportstate 3 1 reset                    # by lid
ibportstate 3 1 speed 1                  # by lid
ibportstate 3 1 width 1                  # by lid
ibportstate -D 0 1 lid 0x1234 arm        # by direct route

---

👑 AUTHOR 👑

Hal Rosenstock < <hal.rosenstock@gmail.com> >

---

and that's a wrap, babe 🫶 this lil masterpiece? it's dated 2013-03-26 and it comes to you from the Open IB Diagnostics crew, living its best life as IBPORTSTATE(8). go forth and query, mwah 💋✨