git.sesse.net Git - cubemap/blob - README

   1 Cubemap is a high-performance, high-availability video reflector,
   2 specifically made for use with VLC.
   3
   4 A short list of features:
   5
   6  - High-performance, through a design with multiple worker threads,
   7    epoll and sendfile (yes, sendfile); a 2GHz quadcore can saturate
   8    10 gigabit Ethernet, given a modern kernel, a modern NIC
   9    and the right kernel tuning.
  10  - High-availability. You can change any part of the configuration
  11    (and even upgrade to a newer version of Cubemap) by changing cubemap.config
  12    and sending a SIGHUP; all clients will continue as if nothing had happened
  13    (unless you delete the stream they are watching, of course).
  14    Cubemap also survives the encoder dying and reconnecting.
  15  - Support for setting max pacing rate through the fq packet scheduler
  16    (depends on Linux 3.13 or newer).
  17  - Reflects anything VLC can reflect over HTTP, even the muxes VLC
  18    has problems reflecting itself (in particular, FLV).
  19  - Multicast support, both for sending and receiving (supports only protocols
  20    that can go over UDP, e.g. MPEG-TS). Supports both ASM and SSM.
  21  - TLS output support, through the TLSe library (requires libtomcrypt)
  22    and the Linux kernel's kTLS (Linux 4.13 or newer). There are a few
  23    limitations; see below.
  24  - IPv4 support. Yes, Cubemap even supports (some) legacy protocols.
  25
  26
  27 HOWTO:
  28
  29   sudo apt install libprotobuf-dev protobuf-compiler libsystemd-dev libtomcrypt-dev
  30   ./configure
  31   make -j4
  32
  33 If you want to use HTTP input (you probably want to), you want VLC 2.2.0
  34 or newer. Then start the VLC encoder with the “metacube” flag to the http
  35 access mux, like this:
  36
  37   cvlc [...] --sout '#std{access=http{metacube,mime=video/x-flv},mux=flv,dst=:4013/test.flv}'
  38
  39 Then look through cubemap.config.sample, copy it to cubemap.config,
  40 compile and start cubemap.
  41
  42 To upgrade cubemap (after you've compiled a new binary), or to pick up new
  43 config:
  44
  45   killall -HUP cubemap
  46
  47 Cubemap will serialize itself to disk, check that the new binary and config
  48 are OK, and then exec() the new version, which deserializes everything and
  49 keeps going.
  50
  51
  52 Notes on TLS support:
  53
  54 Cubemap supports TLS on output, so that you can play video on TLS
  55 web sites without issues with mixed content. TLS on input streams is
  56 not (yet) supported.
  57
  58 TLS requires kTLS, ie., Linux >= 4.13 with CONFIG_TLS enabled. Only cipher
  59 suites supported by kTLS is supposed, ie., AES-128-GCM (if no such cipher
  60 suite is available, the connection will be aborted). If the server is restarted
  61 before the key exchange for a connection is completed, that connection will
  62 not survive the restart, unlike all other connections. (This is a TLSe
  63 limitation.) You can have different certificates on different ports (and
  64 have separate ports for TLS and non-TLS), but SNI is not yet supported.
  65
  66
  67 Munin plugins:
  68
  69 To activate these, symlink them into /etc/munin/plugins. If you don't put
  70 the files in the expected default locations (as done by 'make install'),
  71 you probably want some configuration in /etc/munin/plugin-conf.d/cubemap or
  72 similar, like this:
  73
  74 [cubemap*]
  75 user <something>
  76 env.cubemap_config /etc/cubemap/cubemap.config
  77 env.cubemap_stats /var/lib/cubemap/cubemap.stats
  78 env.cubemap_input_stats /var/lib/cubemap/cubemap-input.stats
  79
  80
  81 Legalese:
  82
  83 Copyright 2013 Steinar H. Gunderson <steinar+cubemap@gunderson.no>.
  84 Licensed under the GNU GPL, version 2. See the included COPYING file.
  85
  86 See tlse/LICENSE for TLSe licensing.