# Rackhound documentation --- --- > macOS app for automated deployment of RUCKUS ICX switches: assess a switch, upgrade firmware, build a stack, adopt to a management platform, or run a guided Full Deploy. --- --- # What is Rackhound? Source: https://docs.neuralconfig.com/rackhound/ Rackhound is a macOS app that takes a RUCKUS ICX switch from the box to a managed, up-to-date deployment — without you memorising the FastIron CLI. You connect to the switch, the app reads its state, and then you pick an operation or run the whole sequence as one guided **Full Deploy**. It is built for the people who actually rack switches: network engineers and installers working on **RUCKUS ICX** hardware over a console cable or SSH. Every operation is a wizard that drives the switch's own CLI for you and shows you exactly what it's sending in a live terminal drawer. ## What it does | Operation | What it's for | |---|---| | **Assess** | Read the switch's model, firmware, stack state, and management status. See [Assessing a switch](https://docs.neuralconfig.com/rackhound/workflows/assessing-a-switch/). | | **Upgrade firmware** | Move a switch to a target FastIron version, hopping through required intermediate releases automatically. See [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/). | | **Build a stack** | Turn standalone units into a stack over their stacking ports. See [Building a stack](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/). | | **Adopt to a platform** | Configure management networking and point the switch at RUCKUS One or SmartZone. See [Adopting to a platform](https://docs.neuralconfig.com/rackhound/workflows/adopting-to-a-platform/). | | **Full Deploy** | Run stack → upgrade → adopt → verify end-to-end from a deployment profile. See [Full Deploy and profiles](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/). | ## How it connects Rackhound talks to the switch two ways: - **Serial console** over a USB-to-serial cable — the way in for a factory-fresh switch with no IP yet. Ports are auto-detected. - **SSH** over the network, once the switch has a management IP. SSH needs **FastIron 9.0 or later**; for older firmware, use the console cable. Both paths are covered in [Connecting to a switch](https://docs.neuralconfig.com/rackhound/setup/connecting-to-a-switch/). ## Which switches Rackhound reads each switch's model from `show version` and recognises eight RUCKUS ICX families — **ICX 8200, 8100, 7850, 7650, 7550, 7450, 7250, and 7150**. All eight are assessed and adopted the same way; what differs is stacking and firmware: | Family | Assess & adopt | Build a stack | Upgrade firmware | |---|---|---|---| | ICX 8200, 7850, 7650, 7550, 7150 | Yes | Yes | Yes | | ICX 8100 | Yes | Yes | Not yet — see [Firmware versions](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/#the-image-filename-each-step-looks-for) | | ICX 7450, ICX 7250 | Yes | No stacking data | Up to 09.0.10a | Per-family version ranges, stack limits, and the hops an upgrade inserts are all in [Firmware versions and upgrade rules](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/). ## Requirements - **macOS 15.0 or later.** - **A USB-to-serial console cable** to reach a factory-fresh switch over its console port, **or** network reachability for **SSH** once the switch has a management IP. - For SSH, the switch must run **FastIron 9.0 or later**. ## Safe by design Rackhound is careful with both your switches and your secrets: - **Nothing is mutated until it's safe.** A firmware upgrade verifies every required image is present before it touches the switch, and Full Deploy skips any phase that isn't needed (already-current firmware, no stack requested). - **Secrets live in the macOS Keychain** — switch passwords and pinned SSH host keys, never in plain preferences. - **Session logs are redacted.** Passwords and config secrets are masked before anything is written to disk. - **No account, no backend, no telemetry.** The app talks only to the switch in front of you. See [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/) for the details. ## Explore the docs ### Set up - [Getting started](https://docs.neuralconfig.com/rackhound/setup/getting-started/): Install Rackhound and connect to a switch over a console cable. - [Connecting to a switch](https://docs.neuralconfig.com/rackhound/setup/connecting-to-a-switch/): Reaching a switch over USB serial console or SSH, and what each path needs. - [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/): The super username, factory defaults, and how Rackhound stores what it learns. ### Workflows - [Assessing a switch](https://docs.neuralconfig.com/rackhound/workflows/assessing-a-switch/): What Rackhound reads on connect — model, firmware, stack state, and port inventory. - [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/): Selecting a .bin or .zip image, and how the upgrade is staged and verified. - [Building a stack](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/): How the Stack wizard joins standalone switches into one stack. - [Adopting to a platform](https://docs.neuralconfig.com/rackhound/workflows/adopting-to-a-platform/): Configuring management networking so a switch reaches its management platform. - [Full Deploy and profiles](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/): Run stack, upgrade, and adoption as one guided sequence, and save it as a profile. ### Reference - [Settings reference](https://docs.neuralconfig.com/rackhound/reference/settings/): Every setting — saved switch passwords, terminal theme, and defaults. - [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/): Keychain storage, redacted session logs, and why there's no backend. - [Firmware versions and upgrade rules](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/): Per-family version support, pulled releases, the hops an upgrade inserts, and the image filenames each step needs. ### More - [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/): Serial and SSH connection failures, and the errors Rackhound surfaces. --- Rackhound is an independent product of NeuralConfig LLC. It is not made, endorsed or supported by RUCKUS Networks. RUCKUS and ICX are trademarks of their respective owners. Need a hand? [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Getting started Source: https://docs.neuralconfig.com/rackhound/setup/getting-started/ From launch to a full read-out of your switch takes about a minute: connect, and Rackhound assesses the switch automatically and drops you on the assessment screen. ## 1. Install and launch Install Rackhound on your Mac and open it. There is no sign-up and no account. The app opens on a **Welcome** screen with three ways to start: | Card | What it does | |---|---| | **Load Deployment Profile** | Open an `.icxprofile` file prepared by your network engineer, then connect. See [Full Deploy and profiles](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/). | | **Connect via Console** | Connect a USB serial cable and explore switch options. | | **Connect via SSH** | Remote connection over the network (**FastIron 9.0+**). | ## 2. Connect to the switch **A factory-fresh switch has no IP yet**, so start with the console cable. Plug a USB-to-serial console cable from your Mac into the switch's console port and choose **Connect via Console**. Rackhound scans your serial ports and flags the likely console adapter with a green **Recommended** badge — pick it and it connects at **9600 8N1**, the ICX console default. Once a switch already has a management IP, you can **Connect via SSH** instead: enter the host, port (default **22**), and username (default **super**). Either path is covered in full — including USB adapters, baud rates, and SSH host keys — in [Connecting to a switch](https://docs.neuralconfig.com/rackhound/setup/connecting-to-a-switch/). :::note[You don't type the password] Rackhound logs in for you. It always uses the username **super** and tries a built-in list of passwords in order, starting with the factory default. See [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/). ::: ## 3. Read the assessment The moment it connects, Rackhound escalates to the switch's privileged prompt and reads its state — model, serial, firmware version, stack status, and whether it's already talking to a management controller. That all lands on the **Assessment** screen. See [Assessing a switch](https://docs.neuralconfig.com/rackhound/workflows/assessing-a-switch/) for what each field means. ## 4. Choose what to do From the assessment you either: - **Choose an Action** — Upgrade Firmware, Build Stack, or open the Terminal, or - **Begin Full Deployment** — if you loaded a deployment profile, run the whole stack → upgrade → adopt → verify sequence in one go. ## Next steps - [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/) — move a switch to a target FastIron version. - [Building a stack](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/) — join standalone units into a stack. - [Adopting to a platform](https://docs.neuralconfig.com/rackhound/workflows/adopting-to-a-platform/) — hand the switch to RUCKUS One or SmartZone. - [Full Deploy and profiles](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/) — the guided end-to-end run. Stuck? [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Connecting to a switch Source: https://docs.neuralconfig.com/rackhound/setup/connecting-to-a-switch/ Rackhound connects to a switch two ways. Use the **serial console** for a factory-fresh switch that has no IP yet, and **SSH** once the switch has a management address on your network. ## Serial console Plug a USB-to-serial console cable from your Mac into the switch's console port and choose **Connect via Console** on the Welcome screen. ### Finding the right port Rackhound enumerates your Mac's serial ports and shows the likely console adapter first, with a green **Recommended** badge. It recognises the common console-cable chipsets by their USB vendor: | Chipset | Shown as | |---|---| | FTDI | FTDI Serial | | Prolific | Prolific Serial | | Silicon Labs CP210x | CP210x Serial | | WCH CH340 | CH340 Serial | Other serial ports are collapsed under **Show N other port(s)** in case your adapter isn't one of the recognised four. Ports are watched live, so plugging the cable in after you open the screen makes it appear. ### Serial parameters Rackhound opens the port at **9600 baud, 8N1** (8 data bits, no parity, 1 stop bit) — the speed RUCKUS ICX consoles ship with. The rate is fixed: there is no baud setting in the app, and it does not try other speeds. Commands are sent with a carriage return only, as ICX expects. :::tip[If it connects but won't talk] The port opens successfully whatever the switch is doing, so a cable that connects but returns nothing — or returns unreadable characters — usually means one of three things: the switch is mid-boot, the console is wired to a data port rather than the console port, or the switch's console speed has been changed away from 9600. Power-cycle it and try again; if the console speed was changed, set it back to 9600 from another terminal first. See [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/). ::: ## SSH Once a switch has a management IP, choose **Connect via SSH** and enter: - **Host / IP** — the switch's management address. - **Port** — default **22**. - **Username** — default **super**. You don't enter a password here — Rackhound tries your configured passwords in order (see [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/)). :::caution[SSH needs FastIron 9.0 or later] Rackhound's SSH client uses modern algorithms only. If the switch runs older firmware, connect over the **console cable** instead and upgrade it first. ::: ### Host keys are pinned (trust on first use) The first time you SSH to a switch, Rackhound records ("pins") its SSH host key in the macOS Keychain. On every later connection it checks the switch is presenting the **same** key. The stored fingerprint is a standard OpenSSH `SHA256:…` value — the same one `ssh-keygen -lf` prints — so you can verify it out of band. If the key ever **changes**, Rackhound refuses to connect and shows: > The switch's SSH identity has changed since you last connected. This can > happen after a factory reset — or it may mean someone is intercepting the > connection. Only reconnect if you know this switch was reset. If you know the switch was genuinely reset or replaced, use **Reset Pin & Reconnect** to pin the new key. If you don't, stop and investigate. Rackhound also **fails closed** — it refuses to connect rather than trust an unverified key — if it can't read or save the pin in the Keychain. See [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/#ssh-host-key-pinning). ## Which one should I use? | Situation | Connect with | |---|---| | Brand-new switch, no IP configured | **Serial console** | | Switch on FastIron below 9.0 | **Serial console** | | Switch already has a management IP and runs FastIron 9.0+ | **SSH** (or console — either works) | ## Next steps - [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/): What Rackhound sends at the login prompt, and what it does when every password is rejected. - [Assessing a switch](https://docs.neuralconfig.com/rackhound/workflows/assessing-a-switch/): The read-only assessment that runs the moment you connect. - [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/): Serial and SSH connection failures, and the host-key mismatch message. --- Trouble connecting? [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/) · [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Logins and passwords Source: https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/ You never type the switch password into a login prompt in Rackhound. The app authenticates for you, using a fixed username and a list of passwords it tries in order. This page explains that list so you know exactly what it will try — and how to add your own. ## The username is always `super` RUCKUS ICX switches log in with the user **super**. Rackhound uses that username on every connection, over both serial and SSH. The SSH connection screen pre-fills **super** and you can leave it as is. ## The password order Rackhound tries passwords in this order until one works: 1. **`sp-admin`** — the built-in factory first-boot password, always tried first. 2. **Your default password** — the entry you starred in Settings (if any). 3. **The rest** of your saved passwords, in order. If you haven't saved any passwords, the app seeds a single default entry with the password **`icx-setup`**. So out of the box the effective order is `sp-admin` then `icx-setup`. :::note[Two different defaults] `sp-admin` is the **factory** password a brand-new ICX switch ships with. `icx-setup` is the password **this app ships with** — the entry it seeds for you, and therefore the one it sets on a switch that forces a password change before you've saved anything of your own. They are different values, and the app tries both. ::: ## Forced password change on first login A factory-fresh ICX switch demands a new password the first time you log in with the factory credentials. Rackhound handles this automatically: when it hits the "new password" / "confirm" prompts, it sets **your default password** — the entry starred in Settings — and carries on. Out of the box that starred entry is `icx-setup`, so on a Mac where you haven't changed anything the switch ends up with the password `icx-setup`. **If you starred a password of your own, the switch gets that one instead.** Either way the password the switch ends up with is already in the list, so the next connection logs in without asking you. :::caution[The starred entry is written to your switches] Because it is the value used for forced password changes, changing which entry is starred changes what Rackhound will set on the *next* factory-fresh switch it meets. Star the password you actually want deployed. ::: ## When every password fails (console only) Over a **console cable**, if every password in the list is rejected, Rackhound does not simply give up. As a last resort it: 1. Sends **Ctrl+Y** to drop the switch into its OS monitor (`OS>`). 2. Runs **`reset_login`**, which clears the switch's configured login credentials. 3. Exits back to the login prompt and logs in with the factory `sp-admin`. 4. Sets the password to **your default password** at the forced-change prompt. This recovers a switch whose password nobody knows — but it **changes the switch's credentials**, so it is not something to trigger by accident. If you have the right password and simply haven't added it yet, disconnect and add it under **Settings → Switch Passwords** before reconnecting. This path is **serial only**. Over SSH there is no OS monitor to reach, so a failed login just reports *"The switch rejected the login credentials."* The same recovery is available when Rackhound re-logs-in after a reboot during an upgrade, but only when the release it just booted is **FastIron 9.x or 10.x**. ## Adding your own passwords If your switches already have custom passwords, add them in **Settings → Switch Passwords**: - Give each entry a **label** and the **password**, and optionally mark one as the **default** (the star) so it's tried right after `sp-admin`. - You can store up to **10** passwords. - Passwords are saved in the macOS **Keychain**, never in plain preferences. The Settings footer restates the rule: *"Passwords are tried in order: sp-admin (built-in), then your default password, then the rest. Username is always 'super'."* See the [Settings reference](https://docs.neuralconfig.com/rackhound/reference/settings/#switch-passwords). ## Getting to the privileged prompt After login, Rackhound escalates to the switch's privileged (`#`) prompt with `enable`, trying each of your passwords and then an empty password. All of the app's read and configuration commands run from there. If login is rejected outright you'll see *"The switch rejected the login credentials."* — add the correct password in Settings and reconnect. ## Next steps - [Settings reference](https://docs.neuralconfig.com/rackhound/reference/settings/): Adding, starring, and removing saved passwords, and the rest of the app's settings. - [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/): Where passwords are stored, and how session logs are redacted before they hit disk. - [Connecting to a switch](https://docs.neuralconfig.com/rackhound/setup/connecting-to-a-switch/): The console and SSH paths that get you to the login prompt in the first place. --- More on where secrets live: [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/) · [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Assessing a switch Source: https://docs.neuralconfig.com/rackhound/workflows/assessing-a-switch/ Every time you connect, Rackhound runs an **assessment** — it logs in, reads the switch's state from its own CLI, and lays it out on one screen. Assessment is read-only; it changes nothing on the switch. ## What it reads Behind the scenes the app disables output paging and runs the standard show-commands, in this order: | Command | What it tells the app | |---|---| | `show stack` | Standalone vs stacked, unit count, and topology | | `show running-config` | Management VLAN and IP, controller config, hostname | | `show version` | Model, firmware version, boot version, serial, MAC, uptime, license | | `show flash` | Flash size and the primary/secondary images | For a stack, it also runs `show version unit ` and `show flash unit ` for each member to check them individually. If it connects while the switch is sitting in the bootloader (a `Monitor>` or `boot>` prompt), assessment stops there and reports the switch as connected but not yet booted. ## What the assessment screen shows The switch identity card shows: - **Model** (or "Unknown Model"), **serial number**, and **MAC address**. - **Firmware** — the running version, with an orange **Update available** badge if a loaded profile targets a newer release. - **Stack** — "Standalone" or "Stacked (*N* units, *topology*)". - **Management** — "Connected: *controller*" or "Not connected". - **Uptime**, and when present the **hostname**, **license**, and (over SSH) the **host / port** you connected to. ## Stack warnings When you assess a stack, Rackhound compares the members and flags mismatches as orange warnings, because they cause problems during upgrades and stack formation: - **Firmware mismatch** — *"Unit `` firmware `` differs from active unit (``)"*. Members should run the same FastIron version. - **Flash mismatch** — *"Unit `` flash mismatch: primary=`

`, secondary=``"*. A member's two flash images disagree. An [upgrade](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/) syncs firmware across a stack, so these usually clear once every member is on the target version. ## After the assessment From here you pick an operation — [Upgrade firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/), [Build a stack](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/), or open the terminal — or, if you loaded a deployment profile, the screen offers **Begin Full Deployment** and a side-by-side comparison of the switch's current state against the profile's targets. See [Full Deploy and profiles](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/). ## Next steps - [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/): Move the switch to a target FastIron release, hopping through required intermediates. - [Building a stack](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/): Join standalone units into a stack over their stacking ports. - [Full Deploy and profiles](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/): Run stack, upgrade, adoption, and verification as one guided sequence. --- [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Upgrading firmware Source: https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/ The Upgrade wizard moves a switch to a target FastIron version. If getting there requires passing through intermediate releases, Rackhound works out the hops for you and runs them one after another, verifying the switch at each step. ## 1. Choose the firmware file Point the wizard at the firmware for your target version — either a **`.bin`** image or the **`.zip`** download from the CommScope / RUCKUS support portal (ICX Setup extracts the right image from the zip). The picker rejects anything that isn't a `.bin` or `.zip`, and warns if the image family doesn't match your switch model — *"This firmware file is for ``. Select the correct file for your switch model."* :::note[Keep intermediate images in the same folder] A multi-hop upgrade needs every release along the path, not just the final one. Put all of them in the **same folder** as your target image — Rackhound serves firmware from that folder and checks every hop is present before it starts. ::: ## 2. Review the upgrade path Rackhound calculates the path from your **current** version to the **target**, inserting any required intermediate releases. FastIron enforces certain hops — for example, older non-UFI builds must pass through `08.0.80f` before any modern UFI image, and `08.0.95+` must go through `09.0.10a` on the way to `10.0.10`. All six rules, and the exact image filename each hop needs, are in [Firmware versions and upgrade rules](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/). The **Upgrade Path** screen shows the plan as numbered steps, each with its image filename, and an estimated time (roughly **8 minutes per step**). A one-step plan is labelled "Direct"; anything longer is "Multi-step". Steps that install a release with known behaviour changes carry notes — SHA1 logins being dropped at 09.0.10, for instance. Read them: most describe work to do [before or after the upgrade](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/#version-specific-gotchas). The wizard won't build a path that FastIron doesn't allow — it stops up front if the target is a [pulled release](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/#releases-rackhound-refuses), if the target [drops support for your model](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/#per-family-version-support), or if your stack is larger than the target version allows. ## 3. Run the upgrade For each step, Rackhound: 1. Starts a local **HTTPS firmware server** and has the switch pull the image with `copy https flash primary port 8443`. 2. Verifies the image landed in the primary flash partition. 3. Saves the config with `write memory`. 4. Boots the new image (`boot system flash primary`, confirming the prompt). 5. Waits for the switch to reboot and come back — up to **10 minutes** — then re-logs-in and confirms `show version` reports the expected version. ```mermaid sequenceDiagram participant M as Your Mac participant S as Switch M->>M: Start HTTPS server on the firmware folder M->>S: copy https flash ... primary port 8443 S->>M: GET /token/image.bin M-->>S: firmware image S->>S: write image to primary flash M->>S: show flash S-->>M: primary = expected image M->>S: write memory M->>S: boot system flash primary + y S->>S: reboot M->>S: log in again, show version S-->>M: running the expected version ``` Each numbered point above is one exchange in that diagram: serve, pull, verify flash, save, boot, re-verify. A step that fails any check stops the run there rather than continuing to the next hop. After the final step it syncs the primary image to the secondary partition (`copy flash flash secondary`) so both partitions match, and for a stack it verifies every member reached the target version. ### The firmware transfer Firmware is served over **HTTPS from your Mac** — not TFTP — on port **8443** (falling back to 8444/8445 if busy), using a freshly generated self-signed certificate and a per-session token. The switch downloads directly from your laptop; nothing goes to the internet. The default transfer timeout is **15 minutes** and is adjustable from 5 to 60 minutes in [Settings](https://docs.neuralconfig.com/rackhound/reference/settings/#firmware-server). See [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/#the-firmware-server) for how the transfer is secured. :::caution[Don't interrupt a reboot] Leaving mid-upgrade cancels it and can leave the switch in an inconsistent state — the wizard warns you before it lets you back out. If a reboot genuinely hangs past 10 minutes you'll see *"Switch did not come back after reboot within 10 minutes"*; wait a little longer or power-cycle. See [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/). ::: ## Version rules worth knowing - **UFI images** apply at FastIron **08.0.90 and later**. - **HTTPS firmware transfer** is supported from **08.0.80**. Very old switches below that don't support the HTTPS pull Rackhound uses. ## What you need - The target firmware file (`.bin` or `.zip`), plus any intermediate images the path requires, all in one folder. - A connected switch (serial or SSH). Over SSH, the switch reconnects itself after each reboot. ## Next steps - [Firmware versions and upgrade rules](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/): Supported ranges, pulled releases, required hops, image filenames, and per-version gotchas. - [Settings reference](https://docs.neuralconfig.com/rackhound/reference/settings/): The firmware server IP and the transfer timeout, when a transfer stalls. - [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/): How the firmware transfer is secured, and the SHA-256 Rackhound records for the image it served. --- [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/) · [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Building a stack Source: https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/ The Stack wizard joins standalone RUCKUS ICX units into a single stack over their dedicated stacking ports. It shows you exactly which cables to plug where, checks they're connected, and then drives FastIron's `stack interactive-setup` for you. ## Before you start The switch you're connected to must be **standalone** — the wizard won't run against a switch that's already in a stack. Its model must support stacking, and your target size can't exceed what the model and firmware allow. ## 1. Choose size and topology - **Units** — how many switches in the stack, from **2** up to the model's maximum (see the table below). - **Topology** — **Ring** (the default and the recommendation) or **Linear**. The maximum depends on the family *and* the firmware it's running: | Family | Maximum units | |---|---| | ICX 8200, 7850, 7650, 7550 | 12 | | ICX 7150 | 12, dropping to **8** from 10.0.10f | | ICX 8100 | **4** (from 10.0.10h) | ICX 7450 and ICX 7250 carry no stacking data in Rackhound and can't be built into a stack here. Full per-family detail is in [Firmware versions](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/#per-family-version-support). :::tip[Prefer a ring] A ring lets any single cable or unit fail without splitting the stack. In a linear topology, a failed cable or unit splits the stack into two independent halves — "split-brain" — and disrupts the network. The wizard flags linear with an on-screen warning for exactly this reason. ::: ## 2. Cable the units and check The wizard draws a live stack diagram and lists the exact cables to connect — each unit's stacking ports to the next, plus a closing cable back to unit 1 for a ring. Cable each unit as shown (the required cable type, such as **25G SFP28**, depends on the model), then press **Check Cables**. Rackhound discovers the physically connected units and marks each expected cable verified or missing. **Build Stack** stays disabled until every cable checks out — until then the button reads *"Fix missing cables, then check again."* :::note[There's a short cooldown] FastIron only allows `stack interactive-setup` to run about every 30 seconds, so **Check Again** has a brief cooldown timer. Wait for it and retry. ::: ## 3. Build the stack With cables verified, press **Build Stack**. Rackhound enables stacking if it isn't already, runs the interactive setup, accepts the discovered chain, and waits for the members to join. It then confirms the expected number of units joined and saves the config with `write memory`. If a member is on a different firmware version, it **syncs firmware from the active controller** as it joins — you'll see a *"Firmware mismatch detected"* note, and the wizard waits longer while the member re-images. If fewer units join than expected, you'll get *"`` of `` switches joined the stack. Check cables on the missing units."* ## After building Re-assess the switch to see the formed stack — unit count, topology, and any remaining per-unit warnings. See [Assessing a switch](https://docs.neuralconfig.com/rackhound/workflows/assessing-a-switch/#stack-warnings). To also upgrade and adopt the stack in one pass, use [Full Deploy](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/), which builds the stack first and then upgrades every member to the target version. ## Next steps - [Firmware versions and upgrade rules](https://docs.neuralconfig.com/rackhound/reference/firmware-versions/): Per-family stack limits and the releases that change them. - [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/): Bring every member of the new stack to the same target version. - [Full Deploy and profiles](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/): Build the stack, upgrade it, and adopt it in one pass from a profile. --- [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/) · [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Adopting to a platform Source: https://docs.neuralconfig.com/rackhound/workflows/adopting-to-a-platform/ The Adoption wizard configures the switch's management networking and points it at a management platform — **RUCKUS One** or **SmartZone** — then watches for the switch to register. ## 1. Pick the platform | Platform | You provide | |---|---| | **RUCKUS One** | **Tenant URL** (e.g. `acme.ruckus.cloud`), plus an optional **registration token**. | | **SmartZone** | **Controller IP address**, plus an optional **controller port**. | Behind the scenes Rackhound applies the matching CLI line — `controller ruckus-one ` or `controller smartzone ` — as the last step of the configuration. :::note[The two optional fields aren't sent to the switch] The RUCKUS One **registration token** and the SmartZone **controller port** are recorded in the deployment profile, but neither appears in the `controller …` line Rackhound writes. The switch uses its own default controller port, and registration is completed on the platform side. Leave both blank unless you're storing them in a profile for your own reference. ::: ## 2. Configure management networking The **Network Config** step sets up how the switch reaches the platform: | Setting | Default | Notes | |---|---|---| | **Management VLAN** | `1` | Applied only if you change it from 1. Valid 1–4095. | | **IP assignment** | **DHCP** | Or **Static IP** — then you enter IP address, subnet mask (default `255.255.255.0`), and default gateway. | | **DNS servers** | Primary `8.8.8.8`, Secondary `8.8.4.4` | **Required for RUCKUS One**, which is reached by hostname. | | **NTP server** | `0.pool.ntp.org` | Recommended so the switch's clock is correct. | :::tip[RUCKUS One needs working DNS] RUCKUS One is reached by its tenant hostname, so the switch must be able to resolve names. Leave DNS set (or point it at your own resolvers) — without it, adoption to RUCKUS One won't connect. ::: ## 3. Apply and wait for the connection Rackhound writes the network and controller configuration, saves it, and then **polls the switch for up to two minutes** (checking every 10 seconds) for a real controller connection — it reads the management interface for an assigned IP and checks the controller status reports "connected" or "registered." Two outcomes are normal: - **Connected** — the switch reported a live controller connection. Done. - **Connection pending** — the configuration applied cleanly but the switch hadn't registered yet within the window: *"Configuration applied, but the switch hasn't reported a controller connection yet. It will keep trying — check the management platform in a few minutes, or retry."* This isn't a failure; the switch keeps trying on its own. If the controller line itself didn't save you'll instead see *"The management controller setting wasn't saved. Check the terminal log for errors."* — see [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/). ## What you need - The platform details above (tenant URL, or controller IP/port). - A reachable management network — DHCP, or static addressing details. To run adoption as part of a full build (stack, upgrade, then adopt) from a profile, use [Full Deploy](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/). ## Next steps - [Full Deploy and profiles](https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/): Package the platform, network, firmware, and stack decisions into one profile. - [Assessing a switch](https://docs.neuralconfig.com/rackhound/workflows/assessing-a-switch/): Confirm the management status the switch reports after adoption. - [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/): What a pending connection means, and what to check when the controller line won't save. --- [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Full Deploy and profiles Source: https://docs.neuralconfig.com/rackhound/workflows/full-deploy-and-profiles/ **Full Deploy** runs the whole sequence — build the stack, upgrade firmware, adopt to a management platform, and verify — in one guided pass, driven by a **deployment profile**. It's how a network engineer packages a target configuration so an installer on site just connects and presses go. ## Deployment profiles (`.icxprofile`) A deployment profile is a file (`.icxprofile`) that carries every decision for a switch: the target firmware version, target stack size and topology, the management platform and its settings, management VLAN and IP assignment, DNS and NTP, and site details. You load one from the **Welcome** screen ("Load Deployment Profile") or by opening the file. Once a profile is loaded, the [assessment](https://docs.neuralconfig.com/rackhound/workflows/assessing-a-switch/) screen shows the switch's current state **side by side** with the profile's targets — firmware (Current / Needs upgrade), stack (Ready / Needs setup), and management (Configured / Needs adoption) — and offers **Begin Full Deployment**. ## The four phases Full Deploy runs these in order, and **skips any phase that isn't needed**: | Phase | Runs when | Skipped when | |---|---|---| | **Build Stack** | The profile asks for more than one unit | No stack requested (target size ≤ 1) | | **Upgrade Firmware** | Current version is below the target | *"Already at or above ``"*, or no target set | | **Connect to Management** | The profile names a platform | No platform in the profile | | **Verify** | Always — re-reads the switch and records the final state | — | ```mermaid flowchart TD A[Begin Full Deployment] --> P{All required firmware
images present?} P -->|no| PF[Stop before any change] P -->|yes| B{Profile asks for
more than one unit?} B -->|no| B2[Skip: no stacking requested] B -->|yes| B3[Build Stack] B2 --> C{Current version
below target?} B3 --> C C -->|no target| C2[Skip: no firmware upgrade requested] C -->|already current| C3[Skip: already at or above target] C -->|yes| C4[Upgrade Firmware] C -->|target or current
version unreadable| CF[Fail the phase] C2 --> D{Profile names
a platform?} C3 --> D C4 --> D D -->|no| D2[Skip] D -->|yes| D3[Connect to Management] D2 --> E[Verify] D3 --> E E --> F[Deployment report] ``` The firmware phase is deliberate about the decision: it upgrades only when the current version is genuinely **below** the target. If the switch is already current it's skipped, and if the profile's target can't be parsed or the current version can't be read, the phase **fails** rather than pretending it succeeded — an unreadable version is not treated as "nothing to do". The image pre-flight at the top of the diagram runs **before** stack formation, because stack formation reboots every unit. A missing intermediate image is therefore caught while the switch is still untouched. ## Safe to run, safe to retry - **Nothing is mutated until everything's checked.** Before any destructive phase, Full Deploy confirms every firmware image the upgrade path needs is present — if any are missing it stops up front with *"This upgrade needs intermediate firmware image(s) that weren't provided…"*, having changed nothing. - **Retry re-runs from the top.** There's no per-phase resume — **Retry Deployment** runs the whole pipeline again. Already-applied configuration is re-applied, not duplicated, so a retry after a mid-run failure is safe. - **Leaving cancels it.** As with the individual wizards, backing out mid-run cancels the deployment and can leave the switch inconsistent — you're warned first. ## The deployment report When Full Deploy finishes it produces a **deployment report** with per-phase durations, the before/after firmware versions, the SHA-256 of the firmware image that was served, the management platform, and the final switch state. An adoption that only reached "connection pending" is recorded honestly as *configured, connection not yet confirmed* — not as a completed adoption. ## What you need - An `.icxprofile` prepared for the switch. - The firmware file(s) the profile's target requires, if an upgrade is part of the plan (see [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/)). - A connected switch (serial or SSH). ## Next steps - [Building a stack](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/): What the stack phase does, and the per-family size limits it enforces. - [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/): What the upgrade phase does to the switch at each hop. - [Adopting to a platform](https://docs.neuralconfig.com/rackhound/workflows/adopting-to-a-platform/): What the management phase writes, and what a pending connection means. --- [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/) · [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Settings reference Source: https://docs.neuralconfig.com/rackhound/reference/settings/ Rackhound's settings are grouped into a few sections. Passwords are stored in the macOS Keychain; everything else is a standard app preference. ## Switch Passwords The passwords Rackhound tries when logging into a switch. See [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/) for how the order works. - Add up to **10** passwords, each with a label. Star one as the **default** so it's tried right after the built-in `sp-admin`. - With none configured, the app uses the built-in default: *"No passwords configured. The built-in default (sp-admin) will be used."* - Passwords are saved to the **Keychain**. If that fails you'll see *"Couldn't save passwords to the Keychain — changes may not persist."* ## Terminal Controls the live terminal drawer that shows what the app is sending to the switch. | Setting | Default | Options | |---|---|---| | **Theme** | Homebrew | Homebrew, System, Ocean, Solarized Dark, Dracula, Monokai | | **Font size** | 13 pt | 9–24 pt | ## Firmware Server Controls the built-in HTTPS server Rackhound uses to serve firmware to the switch during an [upgrade](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/). | Setting | Default | Notes | |---|---|---| | **Server IP Address** | Auto-detect | Or pick a specific local IP if your Mac has several interfaces. | | **Transfer timeout** | 15 minutes | 5–60 minutes. The maximum time to wait for the firmware download plus flash validation. | :::tip[Set the server IP if transfers stall] If your Mac has multiple network interfaces (Wi-Fi, Ethernet, a VPN), auto-detect may pick one the switch can't reach. Choose the IP on the same network as the switch's management/console path. ::: ## Test HTTPS Server A standalone HTTPS server for testing firmware transfers manually from the switch CLI, independent of the upgrade wizard: *"Start a standalone HTTPS server to test firmware transfers manually via CLI."* Choose a folder of firmware files and start it; it shows the address it's listening on (for example `Running on :`) so you can run a `copy https flash …` by hand. Stop it when you're done. ## Next steps - [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/): How the saved-password list is used, and which entry gets written to a switch. - [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/): Where these settings are stored, and what the Keychain holds. - [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/): Where the firmware server settings above actually take effect. --- [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Security and privacy Source: https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/ Rackhound handles switch credentials and pushes firmware, so it's built to be careful with both. Here's exactly what it stores, what it logs, and what leaves your Mac. ## No account, no backend, no telemetry Rackhound has no sign-up and no cloud service. It talks only to the switch in front of you — over the console cable or SSH on your local network — and, during an upgrade, serves firmware to that switch from your own Mac. Nothing is sent to the internet and there is no analytics. ## Secrets live in the Keychain Everything sensitive is stored in the macOS **data-protection Keychain** (service `com.neuralconfig.ICX-Setup`), never in plain preferences: - **Switch passwords** you save in Settings. - **Pinned SSH host keys** (see below). - **Ephemeral TLS material** for the firmware server — generated per session, marked never to sync off the device, and deleted when the server stops. Keychain items are only accessible while the Mac is unlocked. ## SSH host-key pinning Rackhound pins each switch's SSH host key on first connection (trust on first use) and refuses to connect if the key later changes — a guard against someone impersonating the switch. The stored fingerprint is a standard OpenSSH `SHA256:…` value you can verify with `ssh-keygen -lf`. It **fails closed**: if it can't read a pinned key from the Keychain, or can't save a new one, it refuses the connection rather than trusting an unverified key. See [Connecting to a switch](https://docs.neuralconfig.com/rackhound/setup/connecting-to-a-switch/#host-keys-are-pinned-trust-on-first-use) for what to do when a key legitimately changes after a factory reset. ## Session logs are written automatically, and redacted **Every connection is logged.** Rackhound opens a log file the moment a serial or SSH session starts and closes it when the session ends — there is no setting to turn this off. **Reveal Log**, in the terminal drawer, opens the current file in Finder. Logs are written inside the app's sandbox container, under `Library/Logs/Rackhound/`, one file per session named for the time and the connection — for example `2026-07-25_143012_SSH-192.168.1.10-22.log` or `2026-07-25_143012_cu.usbserial-A1B2C3.log`. They are plain text, they are not rotated or deleted for you, and nothing sends them anywhere. Delete them yourself when you no longer want them. Before anything is written, Rackhound **masks secrets**, replacing them with `[redacted]`: - Your saved switch passwords. - Secrets in config lines — the value after `password`, `community`, or `key` (including `enable` passwords, SNMP community strings, and RADIUS/TACACS keys). - SNMPv3 auth and privacy secrets. Redaction works on whole lines, so a secret split across two reads can't slip through. Password prompts aren't echoed by ICX, so typed passwords never reach the log in the first place. ## The firmware server During an upgrade, firmware is served from your Mac over **HTTPS**, not TFTP: - A **self-signed certificate** (RSA 2048, with your Mac's IP as its subject name) is generated in-process each session — no `openssl` shell-out, so it works inside the App Sandbox. - Each session mints a random **per-session token** that must be the first part of the request path; requests without it get a 403. - The server only serves files from the firmware folder you selected, and resolves paths so a request can't escape that folder. Rackhound also records the **SHA-256** of the exact image it served, so you can compare it against the vendor's published hash and detect a tampered file. ## Next steps - [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/): What Rackhound sends at a login prompt, and the console-only credential reset. - [Connecting to a switch](https://docs.neuralconfig.com/rackhound/setup/connecting-to-a-switch/): Host-key pinning in practice, including what to do when a key legitimately changes. - [Settings reference](https://docs.neuralconfig.com/rackhound/reference/settings/): The settings behind the storage described here. --- Questions about how something is stored or transmitted? [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Firmware versions and upgrade rules Source: https://docs.neuralconfig.com/rackhound/reference/firmware-versions/ Before it touches a switch, the [Upgrade wizard](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/) checks the target release against a built-in matrix: is this release safe to run at all, does this model still support it, and what has to be installed on the way there. This page is that matrix, written out. ## Releases Rackhound refuses Three releases are marked **pulled** and cannot be chosen as a target. Picking one stops the wizard with *"Version `` has been pulled and should not be used"*: - **09.0.00** - **09.0.00a** - **09.0.10** Note that `09.0.10` is pulled but **`09.0.10a` is not** — `09.0.10a` is the intermediate release the matrix routes through on the way to 10.0.10. ## Per-family version support | Family | First release | Last supported release | Max stack | |---|---|---|---| | **ICX 8200** | 10.0.10 | — | 12 | | **ICX 8100** | 10.0.10f | — | 4 (from 10.0.10h) | | **ICX 7850** | 08.0.90 | — | 12 | | **ICX 7650** | 08.0.90 | — | 12 | | **ICX 7550** | 08.0.95 | — | 12 | | **ICX 7450** | 08.0.90 | **09.0.10a** | not supported | | **ICX 7250** | 08.0.90 | **09.0.10a** | not supported | | **ICX 7150** | 08.0.90 | — | 12, dropping to **8** from 10.0.10f | The **last supported release** column is the one the wizard enforces: targeting a release past it stops the upgrade with *"`` is not supported past ``"*. ICX 7450 and ICX 7250 were dropped in 10.0.10, so Rackhound will not take either past 09.0.10a. ICX 7150 is absent from 10.0.x before **10.0.10f** — 10.0.10f is the first 10.0.x release for that family, and it is also where the stack limit drops from 12 to 8. **ICX 7450 and ICX 7250 can't be stacked from Rackhound:** Both models are recognised, assessed, and upgraded, but Rackhound carries no stacking-port data for them, so the [Stack wizard](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/) can't build a stack of either. Build those stacks from the switch CLI. ## The hops Rackhound inserts FastIron does not allow every version-to-version jump. When your current and target releases are separated by one of these rules, Rackhound inserts the required release as its own step and runs the steps in order: | Current version | Target version | Hop inserted first | |---|---|---| | Below **08.0.80** (non-UFI) | 08.0.90 or later | **08.0.80f** | | **08.0.80 – 08.0.89** | 09.0.10a or later | **08.0.95** | | **08.0.90 – 08.0.94** | 09.0.10a or later | **08.0.95d** | | **08.0.95 – 08.0.99** | 10.0.10 or later | **09.0.10a** | | **09.0.10a** or later | 10.0.10 or later | none — direct | | **08.0.90** or later | below 09.0.00 | none — direct | Hops chain: a switch on 08.0.70 going to 10.0.10 passes through 08.0.80f, then 08.0.95, then 09.0.10a. Each hop is a full transfer-and-reboot cycle, which is why the wizard estimates roughly **8 minutes per step**. ## The image filename each step looks for Rackhound serves each step's image **by name** from the folder holding the file you selected — so every release on the path must be present in that folder, under the vendor's own filename. These are the names it looks for: | Family | Prefix | Known images | |---|---|---| | ICX 7150, 7450, 7250 | `SPR` | `SPR08080f.bin`, `SPR08090ufi.bin`, `SPR08095ufi.bin`, `SPR08095dufi.bin`, `SPR09010aufi.bin`, `SPR10010fufi.bin` | | ICX 7850, 7650 | `TNR` | `TNR08090ufi.bin`, `TNR08095ufi.bin`, `TNR09010aufi.bin`, `TNR10010ufi.bin` | | ICX 7550 | `GZR` | `GZR08095ufi.bin`, `GZR09010aufi.bin`, `GZR10010ufi.bin` | | ICX 8200 | `RDR` | `RDR10010ufi.bin` | For a release not in that list, Rackhound builds the name from the convention — prefix, then two-digit major, one-digit minor, two-digit patch, the letter suffix, then `ufi.bin`. So 10.0.10g on an ICX 7150 is `SPR10010gufi.bin`. If a required name isn't in the folder, the upgrade stops **before** changing anything, listing what's missing. Rename nothing: the check is on the filename, so a correct image saved under a different name will not be found. **ICX 8100 firmware images aren't in the matrix yet:** Rackhound knows no image filenames for the ICX 8100 family. An 8100 upgrade builds a placeholder name beginning `TBDR…`, which no shipped RUCKUS image matches, so the wizard stops with a missing-image error. Assessment, stacking, and adoption work normally on the ICX 8100 — only the upgrade path is affected. [Contact support](https://support.neuralconfig.com/rackhound?from=docs) if you need to upgrade one. ## Version-specific gotchas For releases that change behaviour, the **Upgrade Path** screen shows notes against the step that installs them. They are reproduced here because most of them describe work to do **before** or **after** the upgrade, not during it. ### Upgrading to 09.0.10 - **SHA1 password users are removed on upgrade** — re-create them with SHA256 or better afterwards, or you will lose those logins. - **`cli timeout` replaces `ip ssh idle-time`, `telnet timeout`, and `console timeout`** — the old lines don't survive. - **Stack-port commands require the `ethernet` keyword** (`stack-port ethernet 1/2/1`). Rackhound already emits the right form for the version it is talking to. - **ICX 7750 is no longer supported** — remove it from the stack before you upgrade. ### Upgrading to 10.0.10 - **The switch (L2) image is discontinued** — 10.0.10 ships a router (L3) image only. - **ICX 7450 and ICX 7250 are no longer supported.** - **ICX 7150 max stack size drops from 12 to 8**, and units with **IDs above 8 must be renumbered** before the upgrade. - **Forwarding-profile migration is required on ICX 7550.** - **Usernames containing colons must be renamed** before upgrading. - **Management VLAN config syntax changes** — this one is migrated automatically. ## Errors from these checks | Message | What it means | |---|---| | *"Version `` has been pulled and should not be used"* | The target is one of the three pulled releases above. | | *"`` is not supported past ``"* | The target is later than the family's last supported release. | | *"`` is not supported on firmware ``"* | The model and target release aren't a valid pairing. | | *"Stack has `` units but `` only supports ``"* | The target release caps the stack smaller than its current size — renumber or split first. | | *"No upgrade path exists from `` to ``"* | No rule chain connects the two releases. | All five stop the wizard **before** anything is sent to the switch. ## Next steps - [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/): Run the upgrade — choosing the image, reviewing the path, and what each step does to the switch. - [Building a stack](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/): Stack sizes, topology, and the cable check — including the per-family limits above. - [Troubleshooting](https://docs.neuralconfig.com/rackhound/troubleshooting/): What to do when an upgrade stops on a missing image or a reboot timeout. --- [Contact support](https://support.neuralconfig.com/rackhound?from=docs). --- # Troubleshooting Source: https://docs.neuralconfig.com/rackhound/troubleshooting/ Fixes for the messages Rackhound shows, grouped by where they appear. If none of these resolves it, [contact support](https://support.neuralconfig.com/rackhound?from=docs). ## Connecting over the console cable **"Couldn't connect to the console cable. Make sure it's plugged in and no other app is using it."** — the port wouldn't open. - Confirm the adapter is plugged in and appears in the port list. Ports are watched live, so it should appear within a second of plugging it in. - If your adapter wasn't flagged **Recommended**, make sure you picked the right `/dev/cu.*` port under **Show other ports**. See [Connecting to a switch](https://docs.neuralconfig.com/rackhound/setup/connecting-to-a-switch/#serial-console). **"Another app is using this port (``). Close other terminal apps and try again."** — a serial port can only be open once. Quit `screen`, minicom, Serial, CoolTerm, or another copy of Rackhound, then retry. **"The switch isn't responding. Try power cycling it."** / **"Couldn't find the console cable. Make sure it's plugged in."** — the port opened but the switch never answered. - Power-cycle the switch and try again — it may be mid-boot. - Confirm the cable is in the switch's **console** port, not a data port. - Rackhound drives the console at a fixed **9600 8N1**. If the switch's console speed was changed away from 9600, connect from another terminal at that speed and set it back before using Rackhound. **The login fails on every password (console only)** — after the last saved password is rejected, Rackhound falls back to a **Ctrl+Y OS-mode `reset_login`**, which clears the switch's login credentials and re-sets the password to your default entry. If you did not intend to reset the switch's credentials, disconnect before the attempts run out and add the correct password first. See [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/#when-every-password-fails-console-only). ## Connecting over SSH **"The switch rejected the login credentials."** — the switch answered but the login failed. Add the correct password under **Settings → Switch Passwords** and reconnect. Remember the username is always **super**. See [Logins and passwords](https://docs.neuralconfig.com/rackhound/setup/logins-and-passwords/). **"SSH handshake failed — the switch closed the connection…"** — usually authentication failed or the switch rejected the SSH algorithms. Verify the credentials and that **SSH is enabled** on the switch. Note SSH needs **FastIron 9.0 or later** — for older firmware, use the console cable. **"Timed out connecting to `:`…"** — the device accepted the TCP connection but never completed the SSH handshake. Confirm the host and port, and that it's actually a switch listening for SSH. ## "The switch's SSH identity has changed" Full message: *"The switch's SSH identity has changed since you last connected. This can happen after a factory reset — or it may mean someone is intercepting the connection. Only reconnect if you know this switch was reset."* Rackhound pinned this switch's SSH host key on the first connection and it's now presenting a different key, so it refuses to connect. - If you **know** the switch was factory-reset or replaced, use **Reset Pin & Reconnect** to trust the new key. - If you don't, stop and investigate before continuing. A related message — *"Could not save the switch's SSH host key to the Keychain…"* or *"Could not read the pinned SSH host key from the Keychain…"* — means Rackhound couldn't verify the key and refused the connection by design. See [Security and privacy](https://docs.neuralconfig.com/rackhound/reference/security-and-privacy/#ssh-host-key-pinning). ## Firmware upgrade **"Please select a .bin firmware image or .zip download"** — the file you chose isn't a firmware image. Select the `.bin`, or the `.zip` from the support portal. **"This firmware file is for ``. Select the correct file for your switch model."** — the image family doesn't match your switch. Download the image for your model. **"No firmware image found for `` in the zip file."** — the `.zip` didn't contain an image for this model. Use the correct download. **Missing intermediate images** — *"This upgrade needs intermediate firmware image(s) that weren't provided… Add the missing image(s) to the firmware folder and try again."* A multi-hop upgrade needs every release on the path. Put them all in the **same folder** as the target image. See [Upgrading firmware](https://docs.neuralconfig.com/rackhound/workflows/upgrading-firmware/#2-review-the-upgrade-path). **"Switch did not come back after reboot within 10 minutes"** — the switch is taking longer than expected to restart. Wait a little longer, or power-cycle it if it doesn't respond. **Transfers stall** — if your Mac has several network interfaces, set a specific **Server IP** in **Settings → Firmware Server** on the same network as the switch, and raise the **Transfer timeout** if needed. See [Settings](https://docs.neuralconfig.com/rackhound/reference/settings/#firmware-server). **"Could not load upgrade matrix."** / **"Cannot determine current firmware version."** / **"Could not determine target version from ``."** — ICX Setup couldn't read the current version, the target from the filename, or its upgrade rules. Re-assess the switch, and confirm you selected the right firmware file. ## Building a stack **"`` of `` switches joined the stack. Check cables on the missing units."** — fewer members joined than requested. Recheck the stacking cables on the units that didn't join and run **Check Cables** again. Remember **Check Again** has a short cooldown. See [Building a stack](https://docs.neuralconfig.com/rackhound/workflows/building-a-stack/). **"Firmware mismatch detected"** — a member is on a different firmware version and will sync from the active controller as it joins; the wizard waits longer while it re-images. This is expected, not an error. ## Adoption **"Configuration applied, but the switch hasn't reported a controller connection yet…"** — the config saved fine but the switch hadn't registered within the two-minute window. This isn't a failure; it keeps trying. Check the management platform in a few minutes, or **Retry**. For **RUCKUS One**, confirm the switch has working **DNS** — see [Adopting to a platform](https://docs.neuralconfig.com/rackhound/workflows/adopting-to-a-platform/#3-apply-and-wait-for-the-connection). **"The management controller setting wasn't saved. Check the terminal log for errors."** — the controller line didn't apply. Open the terminal drawer to see what the switch reported, and retry. ## Still stuck? [Contact support](https://support.neuralconfig.com/rackhound?from=docs).