{"id":29844578,"url":"https://github.com/esnet/udplbd2","last_synced_at":"2025-07-29T16:44:41.542Z","repository":{"id":293555461,"uuid":"951023643","full_name":"esnet/udplbd2","owner":"esnet","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-23T04:47:47.000Z","size":680,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-23T05:41:22.906Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esnet.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,"zenodo":null}},"created_at":"2025-03-19T03:38:03.000Z","updated_at":"2025-05-23T04:47:51.000Z","dependencies_parsed_at":"2025-05-15T23:39:26.314Z","dependency_job_id":null,"html_url":"https://github.com/esnet/udplbd2","commit_stats":null,"previous_names":["esnet/udplbd2"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/esnet/udplbd2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fudplbd2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fudplbd2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fudplbd2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fudplbd2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esnet","download_url":"https://codeload.github.com/esnet/udplbd2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fudplbd2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267719019,"owners_count":24133467,"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","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-07-29T16:44:40.960Z","updated_at":"2025-07-29T16:44:41.517Z","avatar_url":"https://github.com/esnet.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EJFAT Control Plane (udplbd)\n\n## Overview\n\n`udplbd` is the control plane for the EJFAT (ESnet-Jefferson Lab FPGA-Accelerated Transport) project. It provides\na gRPC API that EJFAT workflows use to coordinate changes to EJFAT load balancers. It also provides administration, testing, and debugging tools for EJFAT workflows.\n\n`udplbd` works by updating the P4 tables of the udplb dataplane which is developed via the [ESnet\nSmartNIC](https://github.com/esnet/esnet-smartnic-fw) project. Tables are updated via the sn-p4 API.\nSetting up the data plane is a requirement before running `udplbd start`, as you need an FPGA to control\nfor `udplbd start` to do anything meaningful.\n\nIt is written in Rust for memory safety and to minimize the possibility of data races. It uses SQLite with\nan append-only schema design (configurable retention) to enable seamless recovery and the ability to inspect\nthis historical state of the control plane. udplbd also integrates `turmoil` for testing in simulation.\n\n## Features\n\n- **gRPC Server**: Manages dynamic load balancers.\n- **Static Configuration**: Applies static load balancer configurations from a YAML file.\n- **Mock Server**: Starts the gRPC server with a simulated dataplane.\n- **API Commands**: Interacts with the gRPC control plane.\n- **Dataplane Testing**: Commands for testing the dataplane (e.g., recv, send, doctor, test, print, pcap).\n\n## Installation\n\n### Using Docker\n\n1. **Build the Docker Image**\n\n   ```bash\n   docker build -t udplbd .\n   ```\n\n2. **Run the Docker Container**\n\n   ```bash\n   docker run -d --name udplbd -v /path/to/config.yml:/etc/udplbd/config.yml udplbd\n   ```\n\n### From Source\n\n1. **Clone the Repository**\n\n   ```bash\n   git clone https://github.com/esnet/udplbd2.git\n   cd udplbd2\n   ```\n\n2. **Build the Project**\n\n   ```bash\n   cargo install --path .\n   ```\n\n3. **Run the Application**\n\n  Ensure that the ESnet SmartNIC applications are running, and that the udplb bitfile was flashed to an FPGA.\n  Configure the `/etc/udplbd/config.yml` appropiately then\n\n   ```bash\n   udplbd start\n   ```\n\n## Configuration\n\nAll commands currently require a config file, you can use the example one if you are only using client/dataplane commands.\n\nConfiguration can be provided via a YAML file or environment variables. The configuration file is located at `/etc/udplbd/config.yml` by default, but this can be overridden using the `--config` flag or the `UDPLBD_CONFIG` environment variable.\n\n### Example Configuration File\n\nSee `./etc/example-config.yml`. You can use this file directly plus an `EJFAT_URI` if you are only using client/dataplane commands, this will eventually be the default behavior.\n\n## Usage\n\n### Command-Line Interface\n\nThe `udplbd` command-line interface provides several subcommands for different operational modes and configuration options.\n\n#### Start the gRPC Server\n\n```bash\nudplbd start  # uses /etc/udplbd/config.yml\nudplbd start --config /path/to/config.yml\n```\n\n#### Apply Static Configuration\n\n```bash\nudplbd static --reservation-file /path/to/reservation.yml --apply\n```\n\n#### Start the Mock Server\n\n```bash\nudplbd mock # uses built-in testing config, only works on localhost\n```\n\n#### gRPC API Commands\n\n```bash\nudplbd client reserve --name \"my_lb\" --sender \"192.168.1.123\" --after \"1hour\"\n```\n\n#### Dataplane Testing Commands\n\n```bash\nudplbd dataplane --url \"ejfats://your_auth_token@0.0.0.0:50051\" recv --address \"192.168.1.123\" --port 50052 --command \"cat\"\n```\n\n### API Commands\n\nThe `client` subcommand provides several commands for interacting with the gRPC control plane. Client commands require an `EJFAT_URI` environment variable OR the specified config file to actually be running with `udplbd start` or `udplbd mock`.\n\n- **Reserve a Load Balancer**\n\n  ```bash\n  udplbd client reserve --name \"my_lb\" --sender \"192.168.1.1\" --after \"1hour\"\n  ```\n\n- **Free a Reserved Load Balancer**\n\n  ```bash\n  udplbd client free\n  ```\n\n- **Display Load Balancer Overview**\n\n  ```bash\n  udplbd client overview\n  ```\n\n- **Manage Allowed Sender IP Addresses**\n\n  ```bash\n  udplbd client senders add --addresses \"192.168.1.1\" \"192.168.1.2\"\n  udplbd client senders remove --addresses \"192.168.1.1\"\n  ```\n\n- **Manage Authentication Tokens**\n\n  ```bash\n  udplbd client tokens create --name \"admin\" --resource-type \"ALL\" --permission \"READ\"\n  udplbd client tokens list-permissions\n  udplbd client tokens list-children\n  udplbd client tokens revoke --token 123\n  ```\n\n- **Display Version**\n\n  ```bash\n  udplbd client version\n  ```\n\n### Dataplane Commands\n\nThe `dataplane` subcommand provides several commands for testing the dataplane. Most dataplane commands require an `EJFAT_URI` environment variable OR the specified config file to actually be running with `udplbd start` or `udplbd mock`.\n\n- **Receive EJFAT Events**\n\n  ```bash\n  udplbd dataplane recv --address \"\u003cpublic IP\u003e\" --port 12345 -- /bin/cat\n  ```\n\n- **Send a File**\n\n  ```bash\n  udplbd dataplane send --file /path/to/file.txt\n  ```\n\n- **Perform Tests**\n\n  ```bash\n  udplbd dataplane test --address \"\u003cpublic IP\u003e\" --port 12345 /path/to/test_config.json\n  ```\n\n- **Run Turmoil Network Simulation Tests**\n\n  ```bash\n  udplbd dataplane sim /path/to/turmoil_config.json\n  ```\n\n- **Pretty Print Received UDP Payloads**\n\n  ```bash\n  udplbd dataplane print --address \"0.0.0.0\" --port 50052\n  ```\n\n- **Reassemble Packets from a PCAP File**\n\n  ```bash\n  udplbd dataplane pcap /path/to/pcap_file.pcap\n  ```\n\n## Logging\n\nLogging is configured via the `log_level` parameter in the configuration file or the `--log-level` command-line flag. The default log level is `info`.\n\n## Copyright Notice\n\nESnet-JLab FPGA Accelerated Transport (control plane) [EJFAT (udplbd2)]\nCopyright (c) 2025, The Regents of the University of California, through\nLawrence Berkeley National Laboratory (subject to receipt of any required\napprovals from the U.S. Dept. of Energy). All rights reserved.\n\nIf you have questions about your rights to use or distribute this software,\nplease contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov.\n\nNOTICE.  This Software was developed under funding from the U.S. Department\nof Energy and the U.S. Government consequently retains certain rights.  As\nsuch, the U.S. Government has been granted for itself and others acting on\nits behalf a paid-up, nonexclusive, irrevocable, worldwide license in the\nSoftware to reproduce, distribute copies to the public, prepare derivative\nworks, and perform publicly and display publicly, and to permit others to do so.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesnet%2Fudplbd2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesnet%2Fudplbd2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesnet%2Fudplbd2/lists"}