CDNShark Documentation

Run the Connector as a Service on Linux and macOS

Run as a service, the connector starts on boot and restarts on its own if it stops. This article applies to Private Origin Tunnel and Private LLM Gateway, which use the same connector.

Linux (systemd)

The installer already does this for you. On any Linux with systemd it creates /etc/systemd/system/cdnshark-tunnel.service, enables it and starts it. Day to day you only need these commands:

sudo systemctl status cdnshark-tunnel     # is it running?
sudo systemctl restart cdnshark-tunnel    # restart it
sudo journalctl -u cdnshark-tunnel -f     # follow its logs

If you removed the unit, or installed with --no-start, you can create it by hand. Save this as /etc/systemd/system/cdnshark-tunnel.service:

[Unit]
Description=CDNShark tunnel connector
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/cdnshark-tunnel run
Restart=always
RestartSec=10
User=root
Group=root

# The connector only makes outbound connections, so it can be locked down tightly.
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/cdnshark/tunnel
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
CapabilityBoundingSet=

[Install]
WantedBy=multi-user.target

Then load and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now cdnshark-tunnel

The connector must already be enrolled, by running the install command from the portal once, before the service can connect.

macOS (launchd)

macOS has no systemd. Its service manager is launchd. The installer doesn't set it up, so on a Mac the connector only runs while you keep cdnshark-tunnel run open in a terminal. To make it start on boot and keep running, save this as /Library/LaunchDaemons/com.cdnshark.tunnel.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cdnshark.tunnel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/cdnshark-tunnel</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>ThrottleInterval</key>
    <integer>10</integer>
    <key>StandardOutPath</key>
    <string>/var/log/cdnshark-tunnel.log</string>
    <key>StandardErrorPath</key>
    <string>/var/log/cdnshark-tunnel.log</string>
</dict>
</plist>

Set its owner and permissions, which launchd requires, then load it:

sudo chown root:wheel /Library/LaunchDaemons/com.cdnshark.tunnel.plist
sudo chmod 644 /Library/LaunchDaemons/com.cdnshark.tunnel.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.cdnshark.tunnel.plist

It runs as root, so it can read the connector's key in /etc/cdnshark/tunnel. It starts on every boot, before anyone logs in. If you had cdnshark-tunnel run open in a terminal, stop that one first.

sudo launchctl print system/com.cdnshark.tunnel | grep state   # is it running?
sudo launchctl kickstart -k system/com.cdnshark.tunnel         # restart it
tail -f /var/log/cdnshark-tunnel.log                           # follow its logs

Removing the service

Linux: the uninstall command removes the systemd unit for you. See Remove a Tunnel or Uninstall the Connector.

macOS: unload the launchd job before running the uninstall command. Otherwise launchd keeps trying to restart a connector that no longer exists.

sudo launchctl bootout system/com.cdnshark.tunnel
sudo rm /Library/LaunchDaemons/com.cdnshark.tunnel.plist