{"id":21559566,"url":"https://github.com/giovannibaccichet/ant-net","last_synced_at":"2026-05-15T18:02:07.052Z","repository":{"id":264009670,"uuid":"862380476","full_name":"GiovanniBaccichet/ANT-net","owner":"GiovanniBaccichet","description":"Infrastructure as Code (IaC) for Advanced Network Technologies (ANT) Educational Lab","archived":false,"fork":false,"pushed_at":"2024-12-05T17:20:55.000Z","size":1025,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-24T11:12:04.878Z","etag":null,"topics":["coap-server","education","infrastructure-as-code","mqtt","terraform","vpn","wi-fi","wireguard-vpn"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GiovanniBaccichet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-24T13:58:52.000Z","updated_at":"2024-12-05T17:20:59.000Z","dependencies_parsed_at":"2024-11-21T14:39:11.702Z","dependency_job_id":null,"html_url":"https://github.com/GiovanniBaccichet/ANT-net","commit_stats":null,"previous_names":["giovannibaccichet/ant-net"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiovanniBaccichet%2FANT-net","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiovanniBaccichet%2FANT-net/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiovanniBaccichet%2FANT-net/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiovanniBaccichet%2FANT-net/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GiovanniBaccichet","download_url":"https://codeload.github.com/GiovanniBaccichet/ANT-net/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244155488,"owners_count":20407355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coap-server","education","infrastructure-as-code","mqtt","terraform","vpn","wi-fi","wireguard-vpn"],"created_at":"2024-11-24T09:07:44.521Z","updated_at":"2026-05-15T18:02:02.017Z","avatar_url":"https://github.com/GiovanniBaccichet.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/GiovanniBaccichet/ANT-net\"\u003e\n    \u003cimg src=\"images/logo.png\" alt=\"Logo\" width=\"160\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003eANT Net\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    Infrastructure as Code (IaC) for Advanced Network Technologies (ANT) Educational Lab\n    \u003cbr /\u003e\n    \u003ca href=\"https://antlab.deib.polimi.it/\"\u003e\u003cstrong\u003eANT Lab Website »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\nANT-Net is a self deployable virtual infrastructure that hosts different services that are used in different courses at Politecnico di Milano. In particular it hosts:\n- **VPN Gateway**: \u003cimg src=\"https://github.com/walkxcode/dashboard-icons/blob/main/png/wireguard.png?raw=true\" style=\"width:15px;\"\u003e [Wireguard](https://www.wireguard.com/) server w/ web interface for managing users and remote access to the infrastructure\n- **MQTT Broker**: \u003cimg src=\"https://github.com/walkxcode/dashboard-icons/blob/main/png/emqx.png?raw=true\" style=\"width:15px;\"\u003e [EMQX](https://www.emqx.com/en) server with web interface for managing topics and clients\n- **CoAP Server**: Python-based CoAP server\n- **File Server + Sensor Network**: a RPi network sending wireless data to a centralized file management service\n\nThe diagram below shows the logical organization of the virtual infrastructure, and in particular how the network is segmented to prevent users from communicating with machines on the outside of the virtual lab network.\n\n![ANT-Net Infrastructure](images/proxmox-infra.png)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n### Built With\n\nThe project is build around \u003cimg src=\"https://github.com/walkxcode/dashboard-icons/blob/main/png/proxmox.png?raw=true\" style=\"width:15px;\"\u003e [Proxmox](https://www.proxmox.com/en/). The deployment of VMs is performed through \u003cimg src=\"https://www.terraform.io/img/logo.png\" style=\"width:15px;\"\u003e [Hashicorp Terraform](https://www.terraform.io/), using the [Terraform Provider for Proxmox](https://github.com/bpg/terraform-provider-proxmox) (we tested it with version 0.65.0). Despite being very well documented, said provider lacks some features regarding Proxmox templating and networking, and for that reason I added the scripts in `scripts/`. Additionally, the VM configuration is performed with the scripts in `scripts/vm_configuration`, this since every configuration is very simple, and it would have been totally overkill to use a tool like Ansible.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nThe main goal of this project being a reproducible and easy-to-deploy setup, most of the configurations are automatic and require little to none user interaction.\n\n### Prerequisites\n\nTo successfully deploy the infrastructure, ensure you meet the following requirements:\n\n1. **Proxmox Server**  \n   - A computer running \u003cimg src=\"https://github.com/walkxcode/dashboard-icons/blob/main/png/proxmox.png?raw=true\" style=\"width:15px;\"\u003e [Proxmox Virtual Environment](https://www.proxmox.com/) (tested on version 8.2).  \n   - Ensure that the server is connected to the internet and has at least one separate Network Interface Card (NIC).\n\n2. **Network Interface Configuration**  \n   - **Motherboard NIC**: Reserved for internet access and Proxmox management - will be `vmbr0`.  \n   - **PCIe NIC**: Dedicated to the *VPN-Gateway* virtual machine. This NIC should be configured to be passed through to the VM and exposed publicly for VPN access.\n\n3. **Additional Requirements**  \n   - Sufficient resources (CPU, RAM, and storage) to run the Proxmox environment and the planned virtual machines - in the base config, at least 8 CPU cores and 16 GB RAM.  \n   - Access to a computer or device with Terraform installed (\u003cimg src=\"https://www.terraform.io/img/logo.png\" style=\"width:15px;\"\u003e [Terraform installation guide](https://developer.hashicorp.com/terraform/tutorials)).  \n   - SSH keys for secure access to Proxmox and other virtual machines will be configured in the next step.\n\n4. **Terraform Environment**  \n   - Terraform (version 1.9.8 or later, tested with version 1.9.8).  \n   - The Terraform Proxmox provider configured. Install it via `terraform init` using the provided `proxmox` provider in this repo's `main.tf`.  \n\n\n### Proxmox Authentication\n\nThe Terraform Proxmox provider uses API Token Key authentication. Before starting we need to create a user and generate an API token for that user (more info [here](https://registry.terraform.io/providers/bpg/proxmox/latest/docs)). For this project, user creation, permissions, API Token generation and SSH keys are managed using `scripts/ssh_api_token_setup.sh`.\n\n**It is mandatory to execute that script** - or generate manually a user, assign the correct permissions and generate an API Token - **before proceeding**. It will output the SSH keys, both public and private, in `ssh`, and will output in CLI the Proxmox API Token, which must be copied and will be used by Terraform as authentication.\n\nInside `terraform/terraform.tfvars` put the output of the script, it should be something like:\n\n```\napi_token = \"terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n```\n\n### Installation\n\nTo deploy and configure the machine, ensure you have the following at hand:  \n- **API Token** (generated in the previous step) \n- **Proxmox root password**  \n\nFollow these steps: \n\n#### 1. Configure `variables.tf`\nEdit the `terraform/variables.tf` file to include your configuration details, such as the Proxmox host's IP address and hostname. Below is an example of what the file might look like:\n\n```hcl\nvariable \"proxmox_host\" {\n  default = \"HOSTNAME_HERE\"\n}\n\nvariable \"proxmox_host_ip\" {\n  default = \"10.79.5.250\"\n}\n\nvariable \"api_url\" {\n  default = \"https://10.79.5.250:8006/api2/json\"\n}\n```\n\n#### 2. Populate `terraform.tfvars`\n\nUpdate the `terraform/terraform.tfvars` file with your API Token and Proxmox root password. This step is crucial as the [Terraform Provider for Proxmox](https://github.com/bpg/terraform-provider-proxmox) relies on both token-based and password-based authentication. Here's a template to guide you:\n\n```hcl\napi_token = \"terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\nusername = \"root@pam\"\npassword = \"PASSWORD_HERE\"\n```\n\n#### 3. Configure Default VM Password\n\n\u003e [!CAUTION]  \n\u003e The **default** credentials for the VM template are `antlab/antlab`.\n\nTo set the **default** username and password for the VM template, edit the `terraform/modules/vm-template/main.tf` file. Locate the following section:\n\n```hcl\nuser_account {\n  username = \"antlab\"\n  keys     = [trimspace(data.local_file.ssh_public_key.content)]\n  password = \"antlab\"\n}\n```\n\nThis block specifies:\n- The **username** (antlab)\n- The **password** (antlab)\n- The **SSH keys**, which are automatically configured based on the script in the [Proxmox Authentication](#proxmox-authentication) section.\n\n\u003e [!TIP]  \n\u003e During the creation of each VM, a random password is automatically generated and stored as a Terraform output. To view the generated password, use the following command: `terraform output -json` \n\n#### 4. Initialize and Apply Terraform\n\nOnce the configuration files are updated, navigate to the `terraform/` directory and run the following commands to initialize and apply the Terraform configuration:\n\n```bash\nterraform init\nterraform apply --auto-approve\n```\n\nThis process will download and configure the provider, then deploy the configuration. Note: The deployment may take 15-20 minutes.\n\nFor convenience, you can use this one-liner:\n\n```bash\nterraform init \u0026\u0026 terraform apply --auto-approve\n```\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\n### Remote Access\n\n\u003e [!NOTE]  \n\u003e The virtual infrastructure is completely isolated from the rest of the network. It cannot be accessed or communicate outside of its subnet. To connect to this network, you must use a VPN.\n\nAs a backup access method, we use \u003cimg src=\"https://github.com/walkxcode/dashboard-icons/blob/main/png/wireguard.png?raw=true\" style=\"width:15px;\"\u003e [WireGuard](https://www.wireguard.com/), a high-performance, modern VPN protocol designed for simplicity and speed.\n\nTo manage WireGuard, we use \u003cimg src=\"https://github.com/donaldzou/WGDashboard/raw/main/src/static/app/public/img/logo.png\" style=\"width:15px;\"\u003e [WGDashboard](https://github.com/donaldzou/WGDashboard), an open-source project that provides an intuitive dashboard for managing:  \n- Virtual networks  \n- Peer configurations  \n- Permissions  \n- Bulk creation and deletion of users  \n\nThis dashboard streamlines the administration of the VPN gateway, ensuring efficient management of user access and network configurations.\n\nTo find the local IP address of the VPN, in order to access the segregated subnet, one can use the Proxmox web dashboard, accessing the `VPN-gateway` section:\n\n![ANT-Net Infrastructure](images/proxmox-find-ip.png)\n\n\u003e [!NOTE] \n\u003e When specifying the VPN configuration, ensure that you do not use the IP address from the segregated subnet. Instead, use the IP address assigned to the other network interface (NIC).  \n\nIn this example, the NIC `ens16` has an IP address in the `10.79.0.0/24` subnet (and **not** the `10.10.10.10` one), which in production should be the public-facing NIC.\n\n#### Sharing VPN Configurations\n\nTo distribute VPN configurations (e.g., to students in a course), follow these steps:\n\n1. **Bulk Create Configurations**: Use **WGDashboard** to **bulk create** the desired number of VPN configurations.\n\n2. **Download and Prepare Configurations**:  \n   - Download all the peer configuration files from WGDashboard.  \n   - Place these files into a folder (e.g., `vpn-profiles`).  \n   - Prepare a `.CSV` file (`users.csv`) containing the details of the users you want to share the configurations with.  \n\n3. **Run the Script**: use the provided script, `scripts/vpn-user-list.py`, to associate each configuration with a user and prepare a distribution-ready file.\n\n   The script will:  \n   - Match each VPN configuration to a user from `users.csv`.  \n   - Generate an updated `.CSV` that can be used to bulk send the configurations via tools like the Microsoft Office Word **Mailings** feature.  \n\n   Example structure for `users.csv`, and the *added VPN config (in italic)*:\n\n   | Name       | Email                | Additional Info | *Profile Name*    | *VPN Config*                |\n   | ---------- | -------------------- | --------------- | ----------------- | --------------------------- |\n   | John Doe   | john.doe@email.com   | ...             | *BulkPeer#160...* | \"[Interface] PrivateKey...\" |\n   | Jane Smith | jane.smith@email.com | ...             | ...               | ...                         |\n\nBy automating the process, you can efficiently distribute VPN profiles to a large number of users.\n\nThe script will recognize the original headers, and append new columns to the original data. Files and folders must be specified using command line arguments: \n\n```bash\npython3 vpn-user-list.py [-o output.csv] [-p profiles-folder-path] input.csv\n```  \n\n### MQTT Broker\n\nAs previously mentioned, we use \u003cimg src=\"https://github.com/walkxcode/dashboard-icons/blob/main/png/emqx.png?raw=true\" style=\"width:15px;\"\u003e [EMQX](https://www.emqx.com/en) as the MQTT Broker.  \n\n**Why EMQX?**  \n\n- It is a widely recognized **industry standard** for MQTT broker implementations.  \n- Known for its **stability** and **reliability** when handling large amounts of network traffic.  \n- Provides a **comprehensive web interface** to monitor and manage activity effectively.\n\n---\n\n#### Access Details\n\n1. **Web Interface**:  \n   After connecting to the VPN, the EMQX web interface can be accessed at:  \n   `http://10.10.10.11:18083`\n\n2. **Pub/Sub Functionality**:  \n   For publishing and subscribing to MQTT topics, use the default port:  \n   `1883`\n\n---\n\nMake sure the VPN connection is active before attempting to access the web interface or pub/sub functionalities.\n\n### CoAP Server\n\nWe use a custom **CoAP server** based on [CoAPthon3](https://github.com/Tanganelli/CoAPthon3), tailored to our specific requirements.\n\n---\n\n#### Accessing the CoAP Server\n\nTo access the CoAP server:  \n\n1. **Ensure VPN Connection**:  \n   You must be connected via the **VPN Gateway** to reach the CoAP server.\n\n2. **Connect using IP Address**:  \n   You can reach the CoAP server at `10.10.10.12`, using the default port.\n\n---\n\n\u003e [!NOTE]   \n\u003e The CoAP server is only accessible within the isolated virtual network via the VPN connection.  \n\n### File Server\n\nThe File Server VM serves as a **data collector** from sensors and facilitates **data sharing** with users or students.  \n\n#### Usage Example\n\nIn our setup, the File Server VM is used to:  \n1. **Capture Wi-Fi Network Traffic**:  \n   Sensor nodes (e.g., Raspberry Pis) capture Wi-Fi traffic. Details about the nodes can be found in the [Additional Information](#additional-information) section.  \n\n2. **Upload Packet Captures**:  \n   The nodes upload the captured packet data to the **File Server** over a VPN connection.  \n\n3. **Data Sharing**:  \n   The collected files are shared using a simple Python HTTP server hosted on the File Server.\n\n#### Deployment Considerations\n\n- **VPN-Based Collection**:  \n  Using a VPN simplifies node placement by enabling flexibility in network connectivity.  \n\n- **Alternative Setup**:  \n  Alternatively, one could use **PCI passthrough** to assign another NIC (Network Interface Card) to the File Server (similar to what was done for the *VPN Gateway*). This would allow a direct connection to, for example, a **PoE switch** isolated from the rest of the network.  \n\n\u003e [!NOTE]\n\u003e While a direct connection to an isolated PoE switch was our initial plan, it was deemed infeasible due to limitations in our physical network infrastructure.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Additional Information\n\nMore info here, like firewall configs.\n\n### ANT-nodes\n\nInfo on the custom image + expand filesystem\n\n#### Troubleshooting\n\nIf problem with rfkill:\n\n```bash\nsudo rfkill unblock wifi; sudo rfkill unblock all\n```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- ROADMAP --\u003e\n## Roadmap\n\n- [x] Automatically configure networking\n- [x] Automatically generate API Token\n- [x] Download and patch Ubuntu Cloud image w/ `qemu-guest-agent`\n- [x] Deploy VMs\n- [x] Deploy firewall rules \n- [x] Provision VMs\n  - [x] VPN Gateway\n  - [x] MQTT Broker\n  - [x] CoAP Server\n  - [x] File Server\n- [x] Stress test the infrastructure\n\nSee the [open issues](https://github.com/GiovanniBaccichet/ANT-net/issues) for a full list of proposed features (and known issues).\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the GPLv3 License. See `LICENSE` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nGiovanni Baccichet - `giovanni.baccichet@polimi.it`\n\nProject Link: [https://github.com/GiovanniBaccichet/ANT-Net](https://github.com/GiovanniBaccichet/ANT-Net)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiovannibaccichet%2Fant-net","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiovannibaccichet%2Fant-net","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiovannibaccichet%2Fant-net/lists"}