Update the documentation

README.md

@@ -2,13 +2,22 @@
 
 A Bolt inventory generator for VMs on various providers including orbstack and vmpooler.
 
+## Prerequisites
+
+### System Dependencies
+
+- **Ruby** (version 2.7 or later)
+- **nmap** (required for VMPooler connectivity filtering).  For example, `brew install nmap`
+- **floaty** (required for VMPooler).  For example, `gem install floaty`.
+- **bolt**
+
 ## Usage
 
 This `bolt_dynamic_inventory` gem queries either VMPooler or Orbstack and generates a Bolt inventory.  It can be used in 2 ways:
 
-* **as a gem**.  For more information see [How to use as a gem](./docs/how_to/how_to_use_as_a_gem.md).
-* **as a bolt dynamic inventory plugin**.  For more information see [How to use as a bolt dynamic plugin](./docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md).
+- **as a gem**.  For more information see [How to use as a gem](./docs/how_to/how_to_use_as_a_gem.md).
+- **as a bolt dynamic inventory plugin**.  For more information see [How to use as a bolt dynamic plugin](./docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md).
 
-This repository also explains [How to create a basic dynamic inventory plugin](./docs/how_to/how_to_create_a_basic_bolt_inventory_plugin.md).  
+This repository also explains [How to create a basic dynamic inventory plugin](./docs/how_to/how_to_create_a_basic_bolt_inventory_plugin.md).
 
-For a listing of various how-to guides and design decisions, see [here](./docs/README.md).
+For a listing of various how-to guides and design decisions, see the [documentation](./docs/README.md).

docs/how_to/how_to_setup_the_environment.md

@@ -20,7 +20,29 @@ For more information on how to do the above from the command-line see [Create an
 
 ### VMPooler Provider
 
-Install and configure `floaty`:
+#### Install nmap (Required for VM connectivity filtering)
+
+**macOS:**
+
+```bash
+brew install nmap
+```
+
+**Ubuntu/Debian:**
+
+```bash
+sudo apt-get install nmap
+```
+
+**RHEL/CentOS:**
+
+```bash
+sudo yum install nmap
+# or on newer versions:
+sudo dnf install nmap
+```
+
+#### Install and configure floaty
 
 ```bash
 gem install floaty
@@ -34,6 +56,8 @@ token: your_token
 EOL
 ```
 
+#### Configure Windows credentials
+
 Configure Windows credentials for VMPooler by setting the appropriate environment variable:
 
 ```bash

docs/how_to/how_to_test_vmpooler_inventory_features.md

@@ -7,6 +7,7 @@ This guide shows you how to manually test the VMPooler inventory features to ens
 * Access to VMPooler
 * Bolt installed
 * The bolt_dynamic_inventory module installed
+* `nmap` installed (required for VM connectivity filtering)
 
 ## Test Scenarios
 
@@ -60,6 +61,35 @@ Verify:
 * 'agent' group exists and contains VMs matching the pattern
 * Group facts and configurations are correct
 
+### 4. VM Connectivity Filtering Testing
+
+```bash
+# 1. Create test VMs:
+bundle exec floaty get ubuntu-2004-x86_64
+bundle exec floaty get ubuntu-2004-x86_64
+
+# 2. Note the VM names from the output
+# e.g., "tender-punditry.delivery.puppetlabs.net" and "normal-meddling.delivery.puppetlabs.net"
+
+# 3. Generate inventory (all VMs should be included initially)
+binv generate --provider vmpooler
+
+# 4. Destroy one of the VMs through VMPooler web interface or floaty
+bundle exec floaty delete <one-of-the-hostnames>
+
+# 5. Generate inventory again - destroyed VM should be automatically filtered out
+binv generate --provider vmpooler
+```
+
+Verify:
+
+* Only reachable VMs appear in the inventory
+* Destroyed VMs are automatically excluded from the targets
+* The filtering happens automatically without manual intervention
+* nmap connectivity checks work correctly for both Linux and Windows VMs
+
+**Note:** The connectivity filtering uses `nmap -Pn -p 22` to check SSH port availability, which works for both Linux and Windows VMPooler VMs.
+
 ## Cleanup
 
 After testing, remember to delete your test VMs:
@@ -73,3 +103,8 @@ bundle exec floaty delete <hostname>
 * If inventory generation fails, check VMPooler connectivity
 * Verify VM hostnames in floaty output match expected patterns
 * Check Windows credentials are properly configured if testing Windows VMs
+* **nmap not found error**: Ensure `nmap` is installed on your system (see environment setup guide)
+* **Connectivity filtering issues**:
+  * Verify nmap can reach VMPooler network (test with `nmap -Pn -p 22 <vm-hostname>`)
+  * Check firewall rules if VMs appear unreachable but should be accessible
+  * DNS resolution issues may cause VMs to be filtered out

docs/how_to/how_to_use_as_a_bolt_dynamic_plugin.md

@@ -10,6 +10,8 @@ For more information see [How to create a basic dynamic inventory plugin](./how_
 
 First, refer to the [Environment Setup Guide](how_to_setup_environment.md) and then configure [orbstack](https://docs.orbstack.dev) and [VMPooler](https://vmpooler.com/).
 
+**Important for VMPooler users:** Ensure `nmap` is installed on your system for VM connectivity filtering (see Environment Setup Guide for installation instructions).
+
 If you are going to be using the vmpooler provider, you will need to also follow [How to setup windows credentials for vmpooler](how_to_setup_windows_credentials_for_vmpooler.md)
 
 ## Usage

docs/how_to/how_to_use_as_a_gem.md

@@ -4,7 +4,13 @@
 
 The following shows how to use the [bolt_dynamic_inventory](https://github.com/gavindidrichsen/bolt_dynamic_inventory) as a gem to generate a bolt inventory for multiple providers, including `orbstack` and `vmpooler`.
 
-Then generate an inventory according to the following sections.
+## Prerequisites
+
+For VMPooler provider, ensure `nmap` is installed on your system for VM connectivity filtering:
+
+**macOS:** `brew install nmap`  
+**Ubuntu/Debian:** `sudo apt-get install nmap`  
+**RHEL/CentOS:** `sudo yum install nmap` or `sudo dnf install nmap`
 
 ## Usage
 
@@ -26,7 +32,7 @@ rbenv which binv
 binv                                                                # list all VMs
 binv --groups "agent:^agent,compiler:^compiler"                     # add custom regex groups
 
-# List vmpooler VMs
+# List vmpooler VMs (automatically filters out destroyed/unreachable VMs)
 binv --provider=vmpooler                                            # list all VMs grouping windows and linux
 binv --provider=vmpooler --groups "agent:tender|normal"             # add custom regex groups