]> git.sesse.net Git - cubemap/blob - README
7ae25dfab6fd339b303e91d3a87a79942a33f1bb
[cubemap] / README
1 Cubemap is a high-performance, high-availability video reflector.
2
3 A short list of features:
4
5  - High-performance, through a design with multiple worker threads,
6    epoll and sendfile (yes, sendfile); a 2GHz quadcore can saturate
7    10 gigabit Ethernet (even with TLS) given a modern kernel.
8  - High-availability. You can change any part of the configuration
9    (and even upgrade to a newer version of Cubemap) by changing cubemap.config
10    and sending a SIGHUP; all clients will continue as if nothing had happened
11    (unless you delete the stream they are watching, of course).
12    Cubemap also survives the encoder dying and reconnecting.
13  - Support for setting max pacing rate through the fq packet scheduler.
14  - Reflects anything VLC can reflect over HTTP, even the muxes VLC
15    has problems reflecting itself (in particular, FLV). Can also
16    call out to external programs to receive or fetch streams in arbitrary
17    ways (e.g. through SRT), although of course they do not necessarily
18    have the same intrinsic high-availability reconfiguration support.
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.17 or newer). There are a few
23    limitations; see below.
24  - fMP4 (HLS) output support, generating playlists on-the-fly. Note that this
25    requires some extra metadata currently only set by Nageru (not VLC).
26  - IPv4 support. Yes, Cubemap even supports (some) legacy protocols.
27
28
29 HOWTO:
30
31   sudo apt install libprotobuf-dev protobuf-compiler libsystemd-dev libtomcrypt-dev pkg-config
32   ./configure
33   make -j4
34
35 Cubemap does not in itself understand the format of video streams;
36 it requires HTTP input that is already delineated into headers and blocks,
37 so that it knows what parts of the stream to skip to clients that
38 connect after the stream has been. (The exception is self-synchronizing
39 streams with no headers, such as MPEG-TS. These can also be sent or
40 received over UDP) The input format is specific to Cubemap and is called
41 Metacube (technically, Metacube2, but Metacube1 is long gone and nothing
42 uses it anymore). Currently, you have three options to create Metacube
43 video streams: VLC, Nageru or FFmpeg with a hack.
44
45 For VLC, start the VLC encoder with the “metacube” flag to the http
46 access mux, like this:
47
48   cvlc [...] --sout '#std{access=http{metacube,mime=video/x-flv},mux=flv,dst=:4013/test.flv}'
49
50 Then look through cubemap.config.sample, copy it to cubemap.config,
51 compile and start cubemap.
52
53 Nageru, my free video mixer, can also produce Metacube streams natively,
54 and so can its included transcoder/remuxer Kaeru. See the manual
55 at https://nageru.sesse.net/doc/ for more information.
56
57 If you feel very adventurous, you can use LD_PRELOAD to load
58 ffmpeg_metacube_hack.so into an FFmpeg-using binary. (This is
59 experimental; native Metacube support is vastly preferred.)
60 For instance, here's one way you can use the ffmpeg(1) binary
61 to serve your webcam to Cubemap:
62
63   LD_PRELOAD=ffmpeg_metacube_hack.so ffmpeg -i /dev/video0 -f mpegts -listen 1 'http://[::]:9095'
64
65
66 To upgrade cubemap (after you've compiled a new binary), or to pick up new
67 config:
68
69   killall -HUP cubemap
70
71 Cubemap will serialize itself to disk, check that the new binary and config
72 are OK, and then exec() the new version, which deserializes everything and
73 keeps going.
74
75
76 Notes on TLS support:
77
78 Cubemap supports TLS on output, so that you can play video on TLS
79 web sites without issues with mixed content. TLS on input streams is
80 not (yet) supported.
81
82 TLS requires kTLS for both send and receive, ie., Linux >= 4.17 with CONFIG_TLS
83 enabled. Only cipher suites supported by kTLS is supposed, ie., AES-128-GCM
84 (if no such cipher suite is available, the connection will be aborted). If the
85 server is restarted before the key exchange for a connection is completed,
86 that connection will not survive the restart, unlike all other connections.
87 (This is a TLSe limitation.) You can have different certificates on different
88 ports (and have separate ports for TLS and non-TLS), but SNI is not yet
89 supported.
90
91
92 Munin plugins:
93
94 To activate these, symlink them into /etc/munin/plugins. If you don't put
95 the files in the expected default locations (as done by 'make install'),
96 you probably want some configuration in /etc/munin/plugin-conf.d/cubemap or
97 similar, like this:
98
99 [cubemap*]
100 user <something>
101 env.cubemap_config /etc/cubemap/cubemap.config
102 env.cubemap_stats /var/lib/cubemap/cubemap.stats
103 env.cubemap_input_stats /var/lib/cubemap/cubemap-input.stats
104
105
106 Legalese: 
107
108 Copyright 2013 Steinar H. Gunderson <steinar+cubemap@gunderson.no>.
109 Licensed under the GNU GPL, version 2. See the included COPYING file.
110
111 See tlse/LICENSE for TLSe licensing.