cloudflared icon indicating copy to clipboard operation
cloudflared copied to clipboard

feat: emit explicit errors for the `service` command on unsupported OSes

Open micah-yeager opened this issue 7 months ago • 4 comments

Per the contribution guidelines, this seemed to me like a small enough change to not warrant an issue before creating this pull request. Let me know if you'd like me to create one anyway.

Background

While working with cloudflared on FreeBSD recently, I noticed that there's an inconsistency with the available CLI commands on that OS versus others — namely that the service command doesn't exist at all for operating systems other than Linux, macOS, and Windows.

Contrast cloudflared --help output on macOS versus FreeBSD (truncated to focus on the COMMANDS section):

  • Current help output on macOS:

    COMMANDS:
       update     Update the agent if a new version exists
       version    Print the version
       proxy-dns  Run a DNS over HTTPS proxy server.
       tail       Stream logs from a remote cloudflared
       service    Manages the cloudflared launch agent
       help, h    Shows a list of commands or help for one command
       Access:
         access, forward  access <subcommand>
       Tunnel:
         tunnel  Use Cloudflare Tunnel to expose private services to the Internet or to   Cloudflare connected private users.
    
  • Current help output on FreeBSD:

    COMMANDS:
       update     Update the agent if a new version exists
       version    Print the version
       proxy-dns  Run a DNS over HTTPS proxy server.
       tail       Stream logs from a remote cloudflared
       help, h    Shows a list of commands or help for one command
       Access:
         access, forward  access <subcommand>
       Tunnel:
         tunnel  Use Cloudflare Tunnel to expose private services to the Internet or to   Cloudflare connected private users.
    

This omission has caused confusion for users (including me), especially since the provided command in the Cloudflare Zero Trust dashboard returns a seemingly-unrelated error message:

$ sudo cloudflared service install ...
You did not specify any valid additional argument to the cloudflared tunnel command.

If you are trying to run a Quick Tunnel then you need to explicitly pass the --url flag.
Eg. cloudflared tunnel --url localhost:8080/.

Please note that Quick Tunnels are meant to be ephemeral and should only be used for testing purposes.
For production usage, we recommend creating Named Tunnels. (https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-guide/)

Contribution

This pull request adds a "stub" service command (including the usual subcommands available on other OSes) to explicitly declare it as unsupported on the operating system.

New help output on FreeBSD (and other operating systems where service management is unsupported):

COMMANDS:
   update     Update the agent if a new version exists
   version    Print the version
   proxy-dns  Run a DNS over HTTPS proxy server.
   tail       Stream logs from a remote cloudflared
   service    Manages the cloudflared system service (not supported on this operating system)
   help, h    Shows a list of commands or help for one command
   Access:
     access, forward  access <subcommand>
   Tunnel:
     tunnel  Use Cloudflare Tunnel to expose private services to the Internet or to   Cloudflare connected private users.

New outputs when running the service management subcommands:

$ sudo cloudflared service install ...
service installation is not supported on this operating system
$ sudo cloudflared service uninstall ...
service uninstallation is not supported on this operating system

This keeps the available commands consistent until proper service management support can be added for these otherwise-supported operating systems.

I'm more than happy to make any adjustments to the pull request — just let me know!

micah-yeager avatar Jul 08 '24 15:07 micah-yeager