Table of Contents
  • Docs >
  • Command Line Reference
Shortcuts

Command Line Reference

Command line options across modes

ShimmerCat, as of version 1.5.0 has three modes of operation: devlove, internet and worker, although the free version only has devlove mode. Some modes provide more or less options, and some settings have different defaults across modes.

This is what the three modes are for:

  • devlove: a handy option to run while developing. It enables SOCKS5 by default, relaxes security settings and strives to rely as much information as possible to web developers.

  • internet: an option to run when facing the Internet. It disables SOCKS5 by default, tightens security settings and strives for reliability and stability. In this mode ShimmerCat runs a master process and a number of workers.

  • worker: this mode is used automatically by the worker processes spawned in internet mode. You can also write your own process master.

In any of the modes, you can see which options ara available via the --help sub-option:

$ shimmercat devlove --help
A mode for web developers
...

General options

  • --listen, -l: Network address to bind to. It has several supported formats. If given as an integer port-no, it will bind to that port at the localhost interface 127.0.0.1 (not to 0.0.0.0). It can also be given as a pair ip-number:port-no, in which case it will bind to that ip address and port, or as unix://<abs-or-rel-path, in which case the server will bind to a local Unix socket. This last choice may come handy for different proxy-ing setups.

  • --socks5-listen, -5: Port where to bind the SOCKS5 proxy. Accepts the same formats than the --listen option.

  • --s5-forward, -w: Instructs the SOCKS5 built-in proxy to forward connections which are not handled by local domains. For example, if your devlove.yaml file specifies that www.mysite.com should be served locally, but you have URLs referencing an external site like fonts.google.com, this option will “pass-through” connections to the later domain. Without this option, those connections are blocked.

  • --scratch-dir-name: The name of the scratch directory. By default, it is “.shimmercat.loves.devs”. The scratch directory contains the Redis database that ShimmerCat uses for internal comunications and caching, the local filesystem socket to Redis and the cache of representations.

  • --worker-count: How many workers to span. This option is available only in internet mode.

  • --disable-socks-5: Disable SOCKS5. Use this option for enhanced security if you are abusing devlove mode to serve an actual website. We recommend you to upgrade instead.

  • --enable-socks-5: Use this option to enable SOCKS5 in internet mode.

  • --wait-for-redis-to-start: Time in milliseconds to wait for Redis to start. By default, ShimmerCat makes a short pause of 50 milliseconds before trying to connect to Redis. That is enough in most modern hardware, but in old hardware or in otherwise throttled down CPUs Redis may take longer to start. Use this option in those cases.

  • --working-dir: Directory that ShimmerCat should consider as current. This is entirely equivalent to starting ShimmerCat at that directory.

  • --log-codes: Command line option used to specify what to log. For example, --log-codes=all\\connection can be used to enable all the logs minus logs related to connections. For more details, read the page on logging.

  • --http2https, -t: Gives ShimmerCat a port to make HTTP to HTTPS redirects. For details, see the corresponding section in the Internet mode article. This option is only available on ShimmerCat’s paid version.

Options for development

The following options are handy to debug protocol-specific issues:

  • --disable-http-11: Disable HTTP/1.1. That is, only accept HTTP/2 connections.

  • --disable-http-2: Disable HTTP/2, that is, only accept HTTP/1.1 connections.

When developing a website, it is handy at times to disable all cache directives or even HTTP/2 Push. These two options are for that:

  • --disable-ua-caching: Changes the cache headers to ask the browser not to cache any requests, for all requests in all virtual domains ran by the server. In particular, this removes the etag header and changes the cache-control header to no-cache, no-store, max-age=0, private.

  • --disable-push: Disables HTTP/2 Push in all virtual domains ran by the server. Notice that that otherwise ShimmerCat respects the connection settings indicated by the client as part of a SETTINGS frame.

  • --show-proxied-headers: Shows the headers which are forwarded to an inner application, and the headers which are received by that application.

  • --sim-bandwidth: Part of the network simulator. Limits server bandwidth for a single HTTP/2 connection to the number given here. If you don’t specify a unit, the server will assume bytes per second as the unit. Units accepted are a subset of the units described at Wikipedia’s page: kbit/s, kb/s (kilobits per second), Mb/s, Mbit/s (megabits per second), Kibit/s (kibits per second), Mibit/s (mibits per second), kB/s (kylobytes per second) and MB/s (megabytes per second). Example: --sim-bandwidth=100kb/s.

  • --sim-latency: Part of the network simulator. Adds latency to packets in their way out, by delaying them by the amount of time specified in this option. If no units are specified, ShimmerCat assumes that the time is given in seconds and fractions of a second. Two units are allowed here, s and ms. Example: --sim-latency=110ms.