Shoreline

A very fast pixelflut server with full IPv6 support written in C

Compiling

Dependencies

• SDL2
• libpthread
• libvncserver
• libnuma (numactl)
• libfreetype2

On *buntu/Debian distros use sudo apt install git build-essential libsdl2-dev libpthread-stubs0-dev libvncserver-dev libnuma-dev libfreetype6-dev to install the dependencies.

Use make to build shoreline

Optionally the following environment variables can be set to control how shoreline is built:

• INCLUDE_DIR: Allows to select an include dir other than /usr/include
• OPTFLAGS: Allows to set the optimization flags used for this build
• FEATURES: Allows to select what features shoreline will be built with (see Makefile for available features)

Usage

By default Shoreline runs in headless mode. In headless mode all user frontends are disabled. Use shoreline -f sdl to get a sdl window for drawing

There are a few more commandline switches:

Options:
  -p <port>                        Port to listen on (default 1234)
  -b <address>                     Address to listen on (default ::)
  -w <width>                       Width of drawing surface (default 1024)
  -h <height>                      Height of drawing surface (default 768)
  -r <update rate>                 Screen update rate in HZ (default 60)
  -s <ring size>                   Size of network ring buffer in bytes (default 65536)
  -l <listen threads>              Number of threads used to listen for incoming connections (default 10)
  -f <frontend,[option=value,...]> Frontend to use as a display. May be specified multiple times. Use -f ? to list available frontends and options
  -t <fontfile>                    Enable fancy text rendering using TTF, OTF or CFF font from <fontfile>
  -d <description>                 Set description text to be displayed in upper left corner (default https://github.com/TobleMiner/shoreline)
  -?                               Show this help

Frontend options

When specifying a frontend frontend-specific options may be passed to the frontend. For example the VNC frontend can be configured to use a nonstandard port:

shoreline -f vnc,port=2342

All available frontends and their options can be listed using shoreline -f ?.

Supported Pixelflut commands

PX <x> <y> <rrggbb|rrggbbaa> # Set pixel @(x,y) to specified hex color
PX <x> <y>                   # Get pixel @(x,y) as hex
SIZE                         # Get size of drawing surface
OFFSET <x> <y>               # Apply offset (x,y) to all further pixel draws on this connection

Alpha blending

By default alpha blending is disabled. This might cause images that contain transparency to be displayed incorrectly. You can enable alpha blending at compile time by adding ALPHA_BLENDING to the FEATURES environment variable. However, be warned this will have a large impact on performance since each pixel drawn turns into a memory read, modify, write instead of just a memory write.

Statistics

To enable on-screen statistics display shoreline needs to be passed a TTF (other formats supported by libfreetype2 will work, too) font via the -t option.

When running a system with a graphical frontend chances are you do have some TTF fonts in /usr/share/fonts/TTF/.

Statistics API

There is a special frontend called statistics. When enabled it serves a simple TCP based statistics API (default port 1235). Upon connecting to the statistics API it dumps a JSON object and closes the connection.

This is an example JSON object returned by the API:

{
  "traffic": {
    "bytes": 7292518314,
    "pixels": 405139493
  },
  "throughput": {
    "bytes": 512289334,
    "pixels": 28460518
  },
  "connections": 10,
  "fps": 59
}

Container setup

The awesome Sebastian Bernauer built a Docker based environment that makes running shoreline with fancy monitoring and colorful statistics a breeze: pixelflut-infrastructure

For optimum performance shoreline should be run on a host separate from the Docker host. Trying to run shoreline inside a Docker container might impact performance severely depending on your hardware and Docker configuration.

Troubleshooting

When using shoreline with a lot of clients default resource limits applied to processes may not be sufficient.

sysctl

The default maximum number of allowed vm mappings may not be enough. Consider increasing it by setting

vm.max_map_count = 1000000

in /etc/sysctl.d/50-vm.conf and reloading it using sysctl --system.

security/limits

Shoreline can hit the maximum number of allowed file descriptors quite easily. Increase it by setting

*		soft 	nofile		262144
*		hard 	nofile		262144

in /etc/security/limits.conf.

systemd

When running shoreline through a systemd service you will need to increase the default cgroup limits for larger installations. Consider adding the following to the [Service] section of your shoreline unit file.

TasksMax=infinity
LimitSTACK=infinity
LimitNOFILE=infinity
LimitNPROC=infinity

Hardware vulnerability mitigations

Over the past years an ever-growing set of mitigations for hardware vulnerabilities have been added to Linux. If you are only running trusted code on your system you might want to add mitigations=off to your kernel cmdline. This can result in a considerable performance increase. On Debian this change can by persisted by adding mitigations=off to GRUB_CMDLINE_LINUX in /etc/default/grub and running update-grub.

Reliability

Misbehaving VNC clients can occasionally trigger assertions in the VNC server library. When running shoreline with the VNC frontend exposed to arbitrary clients, adding a VNC multiplexer like VNCmux can improve reliability of shoreline considerably.

IP-Based Rate-Limiting

In order to rate-limit every IP to 10 established connections, you can simply use iptables:

iptables -A INPUT -p tcp -m tcp --dport 1234 --tcp-flags FIN,SYN,RST,ACK SYN -m connlimit --connlimit-above 10 --connlimit-mask 32 --connlimit-saddr -j REJECT --reject-with icmp-port-unreachable ip6tables -A INPUT -p tcp -m tcp --dport 1234 --tcp-flags FIN,SYN,RST,ACK SYN -m connlimit --connlimit-above 10 --connlimit-mask 128 --connlimit-saddr -j REJECT --reject-with icmp6-port-unreachable

Performance

Shoreline can easily handle full 10G line speed traffic on half way decent hardware (i7-6700, 32 GB dual channel DDR4 memory @2400 MHz)

On more beefy hardware (2x AMD EPYC 7821, 10x 8GB DDR4 ECC memory @2666 MHz, 6 memory channels) we are at about 37 Gbit/s

These results were obtained using Sturmflut as a client

VNC

With many VNC clients performance can degrade. Running a VNC multiplexer like VNCmux, even on the same host, can improve performance drastically.