RECEPTOR(1)

📦
version 1.6.6 · 5 versions
, in ubuntu stonking

💖 RECEPTOR(1) 💖

okay bestie, this is RECEPTOR(1) — it lives in the User Commands part of the manual, and yes this whole thing is about receptor, the Main controller daemon. buckle up, it's long, but we're getting through it together 🫶

🌸 NAME 🌸

receptor — Main controller daemon 👑

🦋 SYNOPSIS 🦋

receptor [--<action> [<param>=<value> ...] ...]

✨ DESCRIPTION ✨

so the whole vibe here is: you hand receptor one or more actions, and each action can have a lil pile of <param>=<value> pairs trailing after it. that's the shape of literally every invocation. here's every action the manual lists 💅

  • --help — shows this help. that's it, that's the whole thing 🙈
  • --config <filename> — loads extra config options from a YAML file
  • --bash-completion — generates a completion script for the bash shell
    • to turn it on right now, run . <(receptor --bash-completion) ✨
  • --node — specifies the node configuration of this instance (required, so like, do not skip this one ⚠️)
    • id=<string> — the node ID. defaults to the local hostname
    • datadir=<string> — the directory where node data gets stored (default: /tmp/receptor)
    • firewallrules=<JSON list of JSON dict of JSON data to JSON data> — firewall rules; go read the documentation for the syntax, bestie
    • maxidleconnectiontimeout=<string> — how long a backend connection can sit there with zero traffic before it gets timed out and refreshed
    • receptorkubesupportreconnect=<string>
    • receptorkubeclientsetqps=<string>
    • receptorkubeclientsetburst=<string>
    • **receptorkubeclientsetratelimiter=<string>
fr the last four have no description in the original — the page just lists them, so that's all we got 💀
  • --local-only — runs a self-contained node with no backend
    • local=<bool>
  • --version — displays the Receptor version
  • --log-level — specifies the verbosity level for command output
    • level=<string> — the log level: Error, Warning, Info or Debug (default: error)
  • --trace — enables packet tracing output
  • --control-service — runs a control service
    • service=<string> — the Receptor service name to listen on (default: control)
    • filename=<string> — the filename of a local Unix socket to bind to the service
    • permissions=<int> — socket file permissions (default: 0600)
    • tls=<string> — name of the TLS server config for the Receptor listener
    • tcplisten=<string> — local TCP port, or host:port, to bind the control service to
    • tcptls=<string> — name of the TLS server config for the TCP listener

🎀 Commands that configure resources used by other commands 🎀

  • --tls-server — define a TLS server configuration
    • name=<string> — name of this TLS server configuration (required)
    • cert=<string> — server certificate filename (required)
    • key=<string> — server private key filename (required)
    • requireclientcert=<bool> — require client certificates (default: false)
    • clientcas=<string> — filename of the CA bundle to verify client certs with
    • pinnedclientcert=<[]string (may be repeated)> — pinned fingerprint of the required client certificate
    • skipreceptornamescheck=<bool> — skip verifying ReceptorNames OIDs in the certificate at startup (default: false)
    • mintls13=<bool> — set the minimum TLS version to 1.3. otherwise the minimum is 1.2 (default: true)
  • --tls-client — define a TLS client configuration
    • name=<string> — name of this TLS client configuration (required)
    • cert=<string> — client certificate filename (required)
    • key=<string> — client private key filename (required)
    • rootcas=<string> — root CA bundle to use instead of system trust
    • insecureskipverify=<bool> — accept any server cert (default: false)
    • pinnedservercert=<[]string (may be repeated)> — pinned fingerprint of the required server certificate
    • skipreceptornamescheck=<bool> — if true, skip verifying ReceptorNames OIDs in the certificate at startup
    • mintls13=<bool> — set the minimum TLS version to 1.3. otherwise the minimum is 1.2 (default: true)

🌈 Commands to configure back-ends, which connect Receptor nodes together 🌈

  • --tcp-listener — run a backend listener on a TCP port
    • bindaddr=<string> — local address to bind to (default: 0.0.0.0)
    • port=<int> — local TCP port to listen on (required)
    • tls=<string> — name of the TLS server config
    • cost=<float64> — connection cost (weight) (default: 1.0)
    • nodecost=<JSON dict of string to float64> — per-node costs
    • allowedpeers=<[]string (may be repeated)> — peer node IDs to allow via this connection
  • --tcp-peer — make an outbound backend connection to a TCP peer
    • address=<string> — remote address (Host:Port) to connect to (required)
    • redial=<bool> — keep redialing on a lost connection (default: true)
    • tls=<string> — name of the TLS client config
    • cost=<float64> — connection cost (weight) (default: 1.0)
    • allowedpeers=<[]string (may be repeated)> — peer node IDs to allow via this connection
  • --udp-listener — run a backend listener on a UDP port
    • bindaddr=<string> — local address to bind to (default: 0.0.0.0)
    • port=<int> — local UDP port to listen on (required)
    • cost=<float64> — connection cost (weight) (default: 1.0)
    • nodecost=<JSON dict of string to float64> — per-node costs
    • allowedpeers=<[]string (may be repeated)> — peer node IDs to allow via this connection
  • --udp-peer — make an outbound backend connection to a UDP peer
    • address=<string> — Host:Port to connect to (required)
    • redial=<bool> — keep redialing on a lost connection (default: true)
    • cost=<float64> — connection cost (weight) (default: 1.0)
    • allowedpeers=<[]string (may be repeated)> — peer node IDs to allow via this connection
  • --ws-listener — run an http server that accepts websocket connections
    • bindaddr=<string> — local address to bind to (default: 0.0.0.0)
    • port=<int> — local TCP port to run the http server on (required)
    • path=<string> — URI path to the websocket server (default: /)
    • tls=<string> — name of the TLS server config
    • cost=<float64> — connection cost (weight) (default: 1.0)
    • nodecost=<JSON dict of string to float64> — per-node costs
    • allowedpeers=<[]string (may be repeated)> — peer node IDs to allow via this connection
  • --ws-peer — connect outbound to a websocket peer
    • address=<string> — URL to connect to (required)
    • redial=<bool> — keep redialing on a lost connection (default: true)
    • extraheader=<string> — sends an extra HTTP header on the initial connection
    • tls=<string> — name of the TLS client config
    • cost=<float64> — connection cost (weight) (default: 1.0)
    • allowedpeers=<[]string (may be repeated)> — peer node IDs to allow via this connection

🧚 Commands to configure services that run on top of the Receptor mesh 🧚

  • --command-service — run an interactive command via a Receptor service
    • service=<string> — Receptor service name to bind to (required)
    • command=<string> — command to execute on a connection (required)
    • tls=<string> — name of the TLS server config
  • --ip-router — run an IP router using a tun interface
    • networkname=<string> — name of this network and service (required)
    • interface=<string> — name of the local tun interface
    • localnet=<string> — local /30 CIDR address (required)
    • routes=<string> — comma separated list of CIDR subnets to advertise
  • --tcp-server — listen for TCP and forward via Receptor
    • port=<int> — local TCP port to bind to (required)
    • bindaddr=<string> — address to bind the TCP listener to (default: 0.0.0.0)
    • remotenode=<string> — Receptor node to connect to (required)
    • remoteservice=<string> — Receptor service name to connect to (required)
    • tlsserver=<string> — name of the TLS server config for the TCP listener
    • tlsclient=<string> — name of the TLS client config for the Receptor connection
  • --tcp-client — listen on a Receptor service and forward via TCP
    • service=<string> — Receptor service name to bind to (required)
    • address=<string> — address for the outbound TCP connection (required)
    • tlsserver=<string> — name of the TLS server config for the Receptor service
    • tlsclient=<string> — name of the TLS client config for the TCP connection
  • --udp-server — listen for UDP and forward via Receptor
    • port=<int> — local UDP port to bind to (required)
    • bindaddr=<string> — address to bind the UDP listener to (default: 0.0.0.0)
    • remotenode=<string> — Receptor node to connect to (required)
    • remoteservice=<string> — Receptor service name to connect to (required)
  • --udp-client — listen on a Receptor service and forward via UDP
    • service=<string> — Receptor service name to bind to (required)
    • address=<string> — address for the outbound UDP connection (required)
  • --unix-socket-server — listen on a Unix socket and forward via Receptor
    • filename=<string> — socket filename, which will be overwritten (required) 👀
    • permissions=<int> — socket file permissions (default: 0600)
    • remotenode=<string> — Receptor node to connect to (required)
    • remoteservice=<string> — Receptor service name to connect to (required)
    • tls=<string> — name of the TLS client config for the Receptor connection
  • --unix-socket-client — listen via Receptor and forward to a Unix socket
    • service=<string> — Receptor service name to bind to (required)
    • filename=<string> — socket filename, which must already exist (required)
    • tls=<string> — name of the TLS server config for the Receptor connection

👑 Commands to configure workers that process units of work 👑

  • --work-signing — private key to sign work submissions
    • privatekey=<string> — private key to sign work submissions
    • tokenexpiration=<string> — expiration of the signed json web token, e.g. 3h or 3h30m
  • --work-verification — public key to verify work submissions
    • publickey=<string> — public key to verify signed work submissions
  • --work-command — run a worker using an external command
    • worktype=<string> — name for this worker type (required)
    • command=<string> — command to run to process units of work (required)
    • params=<string> — command-line parameters
    • allowruntimeparams=<bool> — allow users to add more parameters (default: false)
    • verifysignature=<bool> — verify a signed work submission (default: false)
  • --work-kubernetes — run a worker using Kubernetes
  • *worktype=<string>* ** — what we're calling this worker type. Required, bestie, no skipping.
  • *namespace=<string>* ** — the Kubernetes namespace where the pods get born 💫
  • *image=<string>* ** — container image for the worker pod
  • *command=<string>* ** — command to run inside the container (heads up, this overrides the entrypoint)
  • *params=<string>* ** — command-line params you're passing to the entrypoint
  • *authmethod=<string>* ** — literally one of kubeconfig or incluster (default: incluster)
  • *kubeconfig=<string>* ** — the kubeconfig filename (only when authmethod=kubeconfig, iykyk)
  • *pod=<string>* ** — pod definition filename, in json or yaml format
  • *allowruntimeauth=<bool>* ** — let API parameters get passed at runtime (default: false)
  • *allowruntimecommand=<bool>* ** — let image & command be specified at runtime (default: false)
  • *allowruntimeparams=<bool>* ** — let command parameters be added at runtime (default: false)
  • *allowruntimepod=<bool>* ** — let a Pod get passed at runtime (default: false)
  • *deletepodonrestart=<bool>* ** — on restart, delete the pod if it's stuck in pending state (default: true)
  • *streammethod=<string>* ** — how we connect to worker pods: logger or tcp (default: logger)
  • *verifysignature=<bool>* ** — verify a signed work submission (default: false)
  • --work-python — run a worker using a Python plugin 🐍
[DEPRECATION WARNING] This option is not currently being used. This feature will be removed from receptor in a future release. Not me warning you about a glow-up that's getting cancelled 😭
  • *worktype=<string>* ** — name for this worker type (required)
  • *plugin=<string>* ** — Python module name of the worker plugin (required)
  • *function=<string>* ** — receptor-exported function to call (required)
  • *config=<JSON dict with string keys>* ** — plugin-specific configuration

✨ Commands to generate certificates and run a certificate authority ✨

PKI era, let's go 💅

  • --cert-init — initialize PKI CA 👑
    • *commonname=<string>* ** — common name to assign to the certificate (required)
    • *bits=<int>* ** — bit length of the encryption keys of the certificate (required)
    • *notbefore=<string>* ** — effective (NotBefore) date/time, in RFC3339 format
    • *notafter=<string>* ** — expiration (NotAfter) date/time, in RFC3339 format
    • *outcert=<string>* ** — file to save the CA certificate to (required)
    • *outkey=<string>* ** — file to save the CA private key to (required)
    • *osw=<certificates.Oser>* ** — OS wrapper for file operations
  • --cert-makereq — create certificate request 📝
    • *commonname=<string>* ** — common name to assign to the certificate (required)
    • *bits=<int>* ** — bit length of the encryption keys of the certificate
    • *dnsname=<[]string (may be repeated)>* ** — DNS names to add to the certificate
    • *ipaddress=<[]string (may be repeated)>* ** — IP addresses to add to the certificate
    • *nodeid=<[]string (may be repeated)>* ** — receptor node IDs to add to the certificate
    • *outreq=<string>* ** — file to save the certificate request to (required)
    • *inkey=<string>* ** — private key to use for the request
    • *outkey=<string>* ** — file to save the private key to (a fresh new key will be generated ✨)
    • *osw=<certificates.Oser>* ** — OS wrapper for file operations
  • --cert-signreq — sign request and produce certificate 🖋️
    • *req=<string>* ** — certificate request PEM filename (required)
    • *cacert=<string>* ** — CA certificate PEM filename (required)
    • *cakey=<string>* ** — CA private key PEM filename (required)
    • *notbefore=<string>* ** — effective (NotBefore) date/time, in RFC3339 format
    • *notafter=<string>* ** — expiration (NotAfter) date/time, in RFC3339 format
    • *outcert=<string>* ** — file to save the signed certificate to (required)
    • *verify=<bool>* ** — if true, don't prompt the user for verification (default: False)

🌈 SEE ALSO 🌈

The full documentation for receptor is maintained as a Texinfo manual. If the info and receptor programs are properly installed at your site, the command

info receptor

should give you access to the complete manual. Go read it, it's giving complete manual energy 📖

And that's a wrap on receptor! 🎀 This whole thing is receptor 1.6.6, dated June 2026 — like, that's the version you're holding and the month it was stamped, so write it down bestie. Periodt. 💖

📦 where this page comes from