User Manual
API Endpoints
Version 1.0.8
Swagger UI Interface
OrpheAgent provides a Swagger UI interface for users to test APIs at http:// {ORPHEAGENT_HOST } /swagger/index.html#/
(Replace {ORPHEAGENT_HOST} with the IP address or domain name of the server where OrpheAgent is running.)
- Beta version: The Swagger service is enabled by default.
- Production version: You need to manually enable the Swagger service by running:
orphe-agent up -f -d
The OrpheAgent provides a comprehensive set of RESTful API endpoints for managing configurations, dashboards, networks, and data plane functionalities. These endpoints are designed to facilitate secure and efficient operations, leveraging authentication and WebSocket capabilities where applicable.
General Information
- Base URL:
/api/v1
- WebSocket Terminal:
/develop/ws/terminal(GET)- Opens a WebSocket connection to the execution session of the web terminal.
- Requires authentication.
- Get Dashboard Info:
/dashboards/get(GET)- Retrieves system dashboard information, including CPU, memory, and disk usage.
- Requires authentication.
- Save Configuration:
/config(POST)- Saves the provided configuration.
- Requires authentication.
- Load Configuration:
/config(GET)- Loads the current configuration.
- Requires authentication.
Network
- Get Network Statistics:
/network/statistics/ws(GET)- Provides WebSocket-based network traffic statistics.
- Provides WebSocket-based network traffic statistics.
Jump to Service
- Save Configuration:
/jumptoservice/config(POST)- Saves the jump-to-service configuration.
- Requires authentication.
- Load Configuration:
/jumptoservice/config(GET)- Loads the jump-to-service configuration.
- Requires authentication.
- Delete Configuration:
/jumptoservice/config/:name(DELETE)- Deletes the specified jump-to-service configuration.
- Requires authentication
Service
- Get Service Status WebSocket:
/service/status/ws(GET)- Provides real-time notification of OrpheAgent and OrpheLink connection status via WebSocket.
- Maintains persistent WebSocket connection for streaming service status updates.
- Requires authentication.
- Get Service Toggle Status:
/service/toggle(GET)- Retrieves the current toggle state of the service (Control Plane and Data Plane status).
- Returns boolean flags for each service component.
- Requires authentication.
- Set Service Toggle Status:
/service/toggle(POST)- Enables or disables Control Plane and/or Data Plane.
- Requires authentication.
DataPlane
- Node Management:
- Get Node:
/dataplane/node(GET)- Retrieves node information from the data plane.
- Requires authentication.
- Set Node:
/dataplane/node(POST)- Updates node information in the data plane.
- Requires authentication.
- Get Node:
- Neighbor Management:
- Add Neighbor:/dataplane/neighbor/add (POST)
- Adds a new neighbor to the data plane.
- Requires authentication.
- Edit Neighbor:
/dataplane/neighbor/edit/:id(POST)- Edits an existing neighbor in the data plane.
- Requires authentication.
- Delete Neighbor:
/dataplane/neighbor/delete/:id(POST)- Deletes a neighbor from the data plane.
- Requires authentication.
- Add Neighbor:/dataplane/neighbor/add (POST)
- Dataplane Control:
- Start:
/dataplane/start(POST)- Starts the dataplane.
- Requires authentication.
- Stop:
/dataplane/stop(POST)- Stops the data plane.
- Requires authentication.
- Restart:
/dataplane/restart(POST)- Restarts the data plane.
- Requires authentication.
- Get Status:
/dataplane/status(GET)- Retrieves the current status of the data plane.
- Requires authentication.
- Get Status WebSocket:
/dataplane/status/ws(GET)- Provides real-time data plane status via WebSocket.
- Returns comprehensive status information including node status, neighbor information, traffic statistics, OS information, device name, and P2P connection quality assessment.
- Maintains persistent WebSocket connection for streaming status updates.
- Requires authentication.
- Set Status:
/dataplane/status/:status(POST)- Updates the status of the data plane.
- Requires authentication.
- Start:
- Routing:
- Get Route Subnet to Exit:
/dataplane/routesubnettoexit(GET)- Retrieves subnets routed to the exit node in the data plane.
- Requires authentication.
- Set Route Subnet to Exit:
/dataplane/routesubnettoexit(POST)- Configures subnets to route to the exit node in the data plane.
- Requires authentication.
- Get Route Subnet to Exit:
- Relay Addresses:
- Get Relay Addresses:
/dataplane/relayaddrs(GET)- Retrieves relay addresses used by the data plane.
- Requires authentication.
- Set Relay Addresses:
/dataplane/relayaddrs(POST)- Updates relay addresses for the data plane.
- Requires authentication.
- Get Relay Addresses:
- Port Forwarding:
- List:
/dataplane/portforwarding/list(GET)- Lists all port forwarding rules.
- Requires authentication.
- Add:
/dataplane/portforwarding/add(POST)- Adds a new port forwarding rule.
- Requires authentication.
- Delete:
/dataplane/portforwarding/delete/:name(POST)- Deletes a port forwarding rule by name.
- Requires authentication.
- List:
- Access Control List (ACL):
- Set Mode:
/dataplane/acl/mode/:mode(POST)- Sets the ACL mode for the data plane.
- Requires authentication.
- Get Mode:
/dataplane/acl/mode(GET)- Retrieves the current ACL mode of the data plane.
- Requires authentication.
- List:
/dataplane/acl/list(GET)- Lists all ACL rules in the data plane.
- Requires authentication.
- Add:
/dataplane/acl(POST)- Adds a new ACL rule to the data plane.
- Requires authentication.
- Delete:
/dataplane/acl(DELETE)- Deletes an ACL rule from the data plane.
- Requires authentication.
- Set Mode:
- Services:
- List Services:
/dataplane/services/list(GET)- Lists all services in the dataplane.
- Requires authentication.
- Edit Service:
/dataplane/services/edit(POST)- Edits an existing service in the data plane.
- Requires authentication.
- List Services:
- MTU:
- Get MTU:
/dataplane/mtu(GET)- Retrieves the Maximum Transmission Unit (MTU) settings.
- Requires authentication.
- Set MTU:
/dataplane/mtu(POST)- Updates the MTU settings.
- Requires authentication.
- Get MTU:
- Tunnel Mode:
- Get Tunnel Mode:
/dataplane/tunnelmode(GET)- Retrieves the current tunnel mode setting of the data plane (high throughput or low latency).
- Requires authentication.
- Set Tunnel Mode:
/dataplane/tunnelmode(POST)- Sets the tunnel mode for the data plane to optimize for either high throughput or low latency.
- Requires authentication.
- Get Tunnel Mode:
- SNAT (Source Network Address Translation):
- Get SNAT:
/dataplane/snat(GET)- Retrieves the current SNAT (Source Network Address Translation) setting of the data plane.
- Requires authentication.
- Set SNAT:
/dataplane/snat/{status}(POST)- Sets the SNAT (Source Network Address Translation) for the data plane.
- Requires authentication.
- Get SNAT:
- Subnet and End Device:
- Get Subnet List:
/dataplane/subnetlist(GET)- Retrieves a list of subnets in the data plane.
- Requires authentication.
- Get End Device List:
/dataplane/enddevicelist(GET)- Retrieves a list of end devices in the data plane.
- Requires authentication.
- Get Subnet List:
- Portal Authentication:
- Login:
/dataplane/portal/login(POST)- Handles the authentication for the portal.
- Login:
- Hole Punch Event:
- Get Hole Punch Event:
/dataplane/holepunchevent/ws(GET)- Handles WebSocket connections for hole punching events.
- Provides real-time notifications about NAT traversal attempts, including address exchange, hole punch attempts, and connection status updates between peers.
- Requires authentication.
- Get Hole Punch Event:
