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
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
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
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