Cloudflare Docs
Railgun
Visit Railgun on GitHub
Set theme to dark (⇧+D)

Railgun execution

Railgun consists of two programs: rg-listener and rg-sender. rg-listener is to be installed at a hosting provider or end-user environment and listens for WAN connections. rg-sender is to be installed at Cloudflare locations and establishes connections across the WAN.

rg-sender acts as an HTTP proxy and accepts HTTP requests (with the CF-ORIGIN-IP and CF-WAN-ID headers) and sends them across the WAN to the rg-listener which then contacts the real web server.

Both ends use Memcached for page caching for the delta compression. If Memcached is not working then both ends still operate without delta compression.

Both programs write a log file containing detailed information about operation. rg-listener reads a configuration file named rg.config which is assumed to be in the same directory as the program. The location of the configuration file can be set on the command line with the -config option.

​​ Runtime Options

OptionDescription
-config[=| ]PATHThe path to the rg.config configuration file to use
-versionOutput version information and exit

​​ Configuration Parameters

ParameterDescription
wan.ipThe IP on which to listen for WAN connections. Default to an empty string meaning all interfaces.
wan.portThe port on which to listen for WAN connections. Defaults to 2408.
stderr.fileName of log file to write stderr messages to. Useful for debugging crashes.
log.levelThe maximum level of log message to output. 0 = errors only; 1 = informational messages; 5 = debugging. The default is 0.
syslog.addrThe network address (hostname:port) of the syslog server to connect to using UDP, or a path for a connection using a Unix domain socket. Defaults to the empty string which means that the system configured syslog will be used via a Unix domain socket.
lan.timeoutThe number of seconds to wait while trying to connect to a web server or for a read from the server. Defaults to 30.
wan.tlsWhether to use TLS for the WAN connection. Defaults to 1 and should only be set to 0 for testing. If no certificate files are provided, but wan.tls=1 and activate.server is non-empty, rg-listener will attempt to acquire a certificate from the activation server.
memcached.serversSpace separated list of Memcached servers in host:port format that will be used for caching. There is not default and this must be set.
memcached.timeoutThe maximum amount of time (in ms) to wait for retrieval of a cached page from Memcached. The default is 100.
memcached.expirationThe expiration time of individual Memcached items in seconds. The default is 600 seconds (10 minutes). If set to 0 then the expiration time is infinite.
memcached.connectThe host:port for the Memcached server. Defaults to 127.0.0.1:11211.
memcached.limitThe maximum size (in bytes) of pages that will be stored in Memcached. Defaults to 100,000.
stats.enabledDetermines whether statistics are gathered or not. Defaults to 0 (set to 1 for statistics output).
stats.urlSets the URL (for example http://stats.example.com:9090/) to periodically POST stats to. Defaults to empty for disabled.
stats.logDetermines whether stats are periodically written to syslog. Defaults to 0 (set to 1 for logged statistics).
stats.intervalHow often (in minutes) stats are generated (and logged and POSTed to the stats.url). Default is 1 indicating every minute.
stats.listenhost:port on which to listen and create a simple HTTP JSON API through which stats can be read via a GET /. Defaults to empty for disabled.
pid.fileThe name of a file into which the PID will be written. Defaults to an empty string which means that no PID file is created.
cert.fileName of file containing the certificate presented by this server to connections. No default.
key.fileName of file containing the private key for the cert.file. No default.
validate.certWhether to validate the certificate presented when making a TLS connection. Defaults to 1 (meaning perform the validation).
map.fileName of a file containing domain=ip pairs that is used to override DNS and the CF-ORIGIN-IP setting. Defaults to no file.
activation.railgun_hostThe public facing, resolvable, hostname through which the Cloudflare CDN can connect to this rg-listener. DNS lookups are done at request-time. Use in place of activation.public_ip.
activation.public_ipThe external IP (or a hostname which resolves to the IP) of your Railgun instance used for activation and automatic DNS record updates. No default.
activation.token32 character hash used for activation (Refer to Configuration and activation). No default.
activation.heartbeat_intervalInterval, in seconds, between heartbeats to activation server. Defaults to 0/off.
memprofile.fileName of the file to which the heap profile will be written when SIGUSR1 is received. There is no default value which means that the memory profile will not be created and memory profiling will be disabled.
cpuprofile.fileName of the file to which the CPU profile will be written when SIGUSR1 is received. There is no default value which means that the CPU profile will not be created. Note that the SIGUSR1 signal toggles profiling on and off and the file will be written on every transition to off.
cpuprofile.intialWhether to begin profiling immediately on startup. It is only valid when cpuprofile.file is set and valid. It is 0 by default, requiring an explicit signal to begin profiling.
memstats.fileName of the file to which information about current memory use will be written when SIGUSR2 is received. This is intended for internal use.
ca.bundleName of a file containing PEM-encoded CA root certificates that will be used for verifying connections to origin servers using TLS. Defaults to empty string which means use the system roots.
origin.idleconnsSets the number of idle TCP connections that will be kept open to the origin server for connection pooling. Defaults to 1.
insecure.originIf this is set to 1 (to indicate true) then connections to the origin web server will be made insecurely at all times (for example, proxied HTTPS connections will use HTTP). This is only safe if the network topology between Railgun and the origin server cannot be eavesdropped upon. Defaults to 0 (false).
origin.cf-railgunIf set to 1 then a Cf-Railgun header will be sent to the origin web server when the request goes through railgun. Defaults to 0. The Cf-Railgun will not have a compression ratio in it, instead it has the word origin.
compress.dataWhether LZ4 compression is to be enabled or not. The default is 0 (disabled). Set to 1 to enable.
cpu.oversubscribeTuning feature used to set a multiplier on the number of cores available to oversubscribe. Default is 1.
stream.sizeIf the HTTP response body is greater than this number of bytes it will not be delta compressed and the body will be streamed across the WAN as it is read from the HTTP server. Defaults to 250000.

​​ Running

  1. Create a rg.config file containing the parameters above.
  2. Start Memcached and then run rg-listener with the -config option set to the path of the rg.config file. Errors on start will output to stderr.

​​ Signal Handling

Railgun handles some signals for easier daemon control.

​​ SIGHUP

Reload configuration file. Certain configuration options cannot be dynamically changed and require a full restart. The following parameters can be changed at runtime:

  • compress.data
  • lan.timeout
  • log.level
  • map.file
  • memcached.expiration
  • memcached.limit
  • memcached.servers
  • memcached.timeout
  • stats.url
  • syslog.addr
  • validate.cert

​​ SIGQUIT

Perform a graceful shutdown without dropping active connections. Upon successful shutdown, deactivate the Railgun matching the activation.token via the Cloudflare API until the instance is restarted.

​​ SIGUSR2

Perform a binary upgrade by spawning a new child, and then terminating the previously running parent process. This signal is automatically sent during the post-install for binary yum/apt package upgrades.