User Manual
CLI Commands
Version 1.1.9
CLI Commands
OrpheAgent provides a set of CLI commands to manage and operate the agent. Below are the available commands and their functionalities:
Start the Agent
Use the up command to start the OrpheAgent:
orphe-agent upOptions:
-dor--debug: Enable debug mode to provide detailed logs for troubleshooting.-for--foreground: Run the agent in the foreground mode instead of as a daemon.
Stop the Agent
Use the down command to stop the OrpheAgent:
orphe-agent downThis command stops the systemd service when it is active. If the service is not active, it sends a shutdown event to the running foreground agent.
Restar the Agent
Use the restart command to restart the OrpheAgent:
orphe-agent restartThis command stops the running agent and starts it again. It is equivalent to running orphe-agent down followed by orphe-agent up.
Configuration Management
Each option in Configuration Management can be configured individually. Please note that any changes to an option will only take effect after performing the save action. Use the config command to manage configurations:
orphe-agent config ACTIONSupported actions:
save: Save the current configuration to the default configuration file.clean: Clear the configuration and restore default values.show: Display the current configuration in a readable format.
Options:.
-por--provision-key: The registration key for the control plane (example:12D3KooWS).-nor--host-name: The name of the Node (example:orphe-agent).-hor--mgmt-port-http: Custom HTTP port for API Server interaction with the control plane (default:0). Usenoneto disable HTTP management.-sor--mgmt-port-https: Custom HTTPS port for API Server interaction with the control plane (default:0). Usenoneto disable HTTPS management.-cor--controlplane-tun-port: Custom port for control plane tunnel (default:0).-dor--dataplane-tun-port: Custom port for data plane tunnel (default:0).
Use 0 to let the system assign a random port. HTTP and HTTPS management ports cannot both be set to
none. All configured non-zero ports must be unique and available.
Examples:
- Show current configuration:
orphe-agent config show - Save configuration with custom provision key and host name:
orphe-agent config save --provision-key 12D3KooWS --host-name my-agent - Disable HTTP management and keep HTTPS management enabled
orphe-agent config save --mgmt-port-http none --mgmt-port-https 443 - Reset configuration to default
orphe-agent config clean
Profile Management
Use the profile command to manage multiple configuration profiles:
orphe-agent profile ACTION
Supported actions:
list: Display all available profiles and their usage status.create: Create a new profile with the specified name.delete: Delete an existing profile.use: Switch to and activate a specific profile, then reload OrpheAgent with the selected profile.
Options:
-nor--name: The name of the profile (required for create, delete, and use actions).
Examples:
- List all profiles:
orphe-agent profile list - Create a new profile named "production":
orphe-agent profile create -n production - Switch to the "production" profile:
orphe-agent profile use -n production - Delete the "staging" profile:
orphe-agent profile delete -n staging
Note: The default profile cannot be deleted. You must switch to a different profile before deleting the current one. Deleting a profile requires confirmation. Type
yeswhen prompted to complete the deletion.
Provision Management
Use the provision command to configure discovery settings for the provision process:
orphe-agent provision ACTIONSupported actions:
-
save: Save the current provision configuration. -
clean: Clear the provision configuration and restore default values. -
show: Display the current provision configuration in a readable format.
Options:
-
-xor--multicast: Enable or disable Multicast discovery (trueorfalse). -
-mor--mdns: Enable or disable MDNS discovery (trueorfalse). -
-ror--relay: Enable or disable Relay discovery (trueorfalse).
Only
trueorfalse(case-insensitive) are accepted for each flag.
Examples:
- Show current provision settings:
orphe-agent provision show - Enable Multicast and MDNS, disable Relay:
orphe-agent provision save --multicast true --mdns true --relay false - Reset provision configuration to default:
orphe-agent provision clean
Control Plane P2P Management
Use the controlplane-p2p command to configure P2P settings for the control plane:
orphe-agent control-plane-p2p ACTION
Supported actions:
save: Save the current P2P settings.show: Display the current P2P configuration.clean: Reset P2P configuration to default values.
Flags:
-dor--dht: Enable or disable DHT Discover (trueorfalse).-uor--udp-hole-punch: Enable or disable UDP Hole Punch (trueorfalse).-ror--relay: Enable or disable Relay Transport (trueorfalse).
Only
trueorfalse(case-insensitive) are accepted for each flag.
Examples:
- Show current P2P settings:
orphe-agent control-plane-p2p show - Enable DHT and Relay, disable UDP Hole Punch and MDNS:
orphe-agent control-plane-p2p save --dht true --relay true --udp-hole-punch false --mdns false - Reset P2P configuration to default:
orphe-agent control-plane-p2p clean
Data Plane P2P Management
Use the dataplane-p2p command to configure P2P settings for the data plane:
orphe-agent dataplane-p2p ACTION
Supported actions:
save: Save the current P2P settings.show: Display the current P2P configuration.clean: Reset P2P configuration to default values.up: Bring up the data plane.down: Bring down the data plane.
Options:
-dor--dht: Enable or disable DHT Discover (trueorfalse).-uor--udp-hole-punch: Enable or disable UDP Hole Punch (trueorfalse).-ror--relay: Enable or disable Relay Transport (trueorfalse).-bor--dataplane-on-boot: Enable or disable Data Plane on boot (trueorfalse).-sor--snat: Enable or disable SNAT (Source Network Address Translation) for data plane traffic (trueorfalse).-tor--tun-mode: Data plane tunnel mode:low_latencyorhigh_throughput(default:high_throughput).
Only
trueorfalse(case-insensitive) are accepted for boolean flags.
Examples:
- Show current P2P settings:
orphe-agent dataplane-p2p show - Enable DHT and Relay, disable UDP Hole Punch :
orphe-agent dataplane-p2p save --dht true --relay true --udp-hole-punch false - Set data plane tunnel mode to low latency:
orphe-agent dataplane-p2p save --tun-mode low_latency - Enable SNAT for data plane traffic
orphe-agent dataplane-p2p save --snat true - Bring up the data plane
orphe-agent dataplane-p2p up - Bring down the data plane
orphe-agent dataplane-p2p down - Reset P2P configuration to default:
orphe-agent dataplane-p2p clean
System Check
Run the system-check command to perform a system compatibility check for OrpheAgent:
orphe-agent system-check
This command verifies whether the system supports the required features for the agent to function correctly.
Status Command
Use the status command to check the status of OrpheAgent:
orphe-agent status
Options:
-dor--dp-link-status: Show the status of the links in data plane.-cor--cp-link-status: Show the status of the link in control plane.-nor--nat-type: Show the detected NAT type and P2P compatibility description.
Without options, this command displays service status, control plane link status, and data plane link status. With an option, it displays the requested status only, including metrics such as latency, jitter, and data rate for link status commands.
Examples:
- Show all status information:
orphe-agent status - Show data plane link status only:
orphe-agent status --dp-link-status - Show control plane link status only:
orphe-agent status --cp-link-status - Show NAT type:
orphe-agent status --nat-type
Help Command
Use the help command to get help with a specific subcommand:
orphe-agent help
This command displays detailed usage information and available options for the specified subcommand. For example, to get help for the up command:
orphe-agent help up
Version Command
Use the version command to print the current version of the OrpheAgent CLI:
orphe-agent version
This command outputs the version information of the installed OrpheAgent binary, which is useful for troubleshooting and verifying deployments.
Update Command
Use the update command to check for available updates and install the latest version of OrpheAgent:
orphe-agent update
This command checks for a newer version of OrpheAgent, downloads the update, and installs it automatically.
Options:
-cor--check: Only check for updates without installing.
Examples:
- Check for updates and install:
orphe-agent update - Only check if an update is available
orphe-agent update --check
Command Details
up/u: Initializes necessary network and system resources and starts the agent.down/d: Stops the agent and cleans up resources.restart/r: Stops the agent and starts it again, applying any configuration changes.config/c: Provides options to save, clean, or display configurations. It also allows setting specific parameters such as provision key, host name, and port assignments for management and tunnel communications.profile/pf: Manages multiple configuration profiles, allowing users to create, delete, list, and switch between different profiles. Supports actions:list,create,delete,use.provision/p: Configure discovery settings for the provision process, including Multicast, MDNS, and Relay options. Supports actions:save,show,clean.controlplane-p2p/cp-p2p: Configure P2P settings for the control plane, including DHT, Relay, UDP Hole Punch, and MDNS. Supports actions:save,show,clean.dataplane-p2p/dp-p2p: Configure P2P settings for the data plane, including DHT, Relay, UDP Hole Punch, MDNS Discover, Data Plane on Boot, SNAT (Source Network Address Translation), and tunnel mode (low_latency or high_throughput). Supports actions:save,show,clean,up,down.system-check/sc: Performs a diagnostic check to ensure system compatibility and provides feedback on any issues.status/s: Displays the current status of OrpheAgent, including both the links status between OrpheAgents and the link status between OrpheAgent and OrpheLink.help/h: Displays detailed usage information and available options for a specific subcommand.version/v: Prints the currently installed OrpheAgent CLI version information, useful for troubleshooting and version verification.update/upd: Checks for available updates and installs the latest version of OrpheAgent. Use--checkto only check for updates without installing.
For additional help, refer to the project documentation or use orphe-agent help to view detailed command descriptions.
