README.rst 6.77 KB
Newer Older
ale's avatar
ale committed
1

ale's avatar
ale committed
2
3
4
=========
autoradio
=========
ale's avatar
ale committed
5

ale's avatar
ale committed
6
7
8
9
10
The *autoradio* service aims to provide a reliable, fault-tolerant
Icecast streaming cluster for audio and video. It provides all the
necessary components to ensure that the traffic from the source to the
clients is uninterrupted, even in face of high load or server crashes.
All this, if possible, without any operator intervention.
ale's avatar
ale committed
11
12
13
14

It is a full-stack service, meaning that it includes its own DNS and
HTTP servers, for full control of the request flow.

ale's avatar
ale committed
15
Autoradio works by using etcd_ to coordinate the various nodes and store
ale's avatar
ale committed
16
17
the global mount configuration. The intended target is a set of
homogeneous servers (or virtual machines) dedicated to this purpose.
ale's avatar
ale committed
18
Autoradio also needs a dedicated DNS domain (or a delegation for a
ale's avatar
ale committed
19
20
21
22
23
24
25
26
subdomain).


Installation
------------

The simplest installation method is probably to use the pre-built
Debian packages (only available for amd64 at the moment), by placing
ale's avatar
ale committed
27
this line in ``/etc/apt/sources.list.d/autoradio.list``::
ale's avatar
ale committed
28

ale's avatar
ale committed
29
    deb http://www.incal.net/ale/debian autoradio/
ale's avatar
ale committed
30
31
32
33

And then running::

    $ sudo apt-get update
ale's avatar
ale committed
34
    $ sudo apt-get install etcd autoradio
ale's avatar
ale committed
35
36
37
38

This will install and start the necessary jobs (which will initially
fail due to the missing configuration).

ale's avatar
ale committed
39
Edit ``/etc/default/autoradio`` and set, at least, the ``DOMAIN``
ale's avatar
ale committed
40
41
42
43
variable to what you've assigned to the cluster. The jobs will
automatically start as soon as the configuration is saved.


44
45
46
47
48
49
50
51
52
53
54
55
56
57
Full cluster install procedure
++++++++++++++++++++++++++++++

This assumes that you have an existing domain name (here
*example.com*) that you control, and that you will run the cluster
under a sub-domain (*radio.example.com*). Follow these steps to
bootstrap a new streaming cluster:

#. Make sure that, on each of your servers, the output of ``hostname
   -f`` is the fully-qualified hostname of the machine, and that it
   resolves to its public IP (possibly using ``/etc/hosts``).

#. On every server, run the above-mentioned steps to set up the APT
   repository and install (do not configure) the ``etcd`` and
ale's avatar
ale committed
58
   ``autoradio`` packages.
59
60
61
62
63
64
65
66
67
68

#. Pick one of your servers and add a delegation for
   *radio.example.com* to it. For instance, with ``bind``::

     radio  IN   NS  3600  machine1.example.com.

#. On *machine1*, edit ``/etc/default/etcd`` and set
   ``BOOTSTRAP=1``. Once you save the file, the ``etcd`` daemon will
   start with an empty database.

ale's avatar
ale committed
69
#. On *machine1*, edit ``/etc/default/autoradio`` and set
70
71
72
73
74
75
76
77
78
79
   ``DOMAIN=radio.example.com``. This will start the ``radiod`` and
   ``redirectord`` daemons, and you will be able to serve DNS records
   for the *radio.example.com* zone. Check with::

     $ ping -c1 radio.example.com

   This should send a ping to *machine1*.

#. Set up all other machines, setting
   ``ETCD_SERVER=etcd.radio.example.com`` in ``/etc/default/etcd`` and
ale's avatar
ale committed
80
   ``DOMAIN=radio.example.com`` in ``/etc/default/autoradio``.
81
82


ale's avatar
ale committed
83
84
85
86
87
88
89
90
91
92
93
94
Securing etcd
+++++++++++++

In a production cluster, you will want to limit access to the *etcd*
daemons so that only the other nodes can connect to it. While it is
possible to do this with firewall rules, the dynamic membership of the
cluster may make this difficult. We suggest using instead *etcd*'s
support for X509 client authentication, together with a tool to manage
an online CA (such as autoca_). This way, enrolling a new machine in
the cluster only requires generating a new client certificate, and no
other configuration.

ale's avatar
ale committed
95
96
97
Install the CA certificate in ``/etc/autoradio/etcd_ca.pem``, the client
certificate in ``/etc/autoradio/etcd_client.pem`` and its private key in
``/etc/autoradio/etcd_client.key``, and the clients will connect to
ale's avatar
ale committed
98
99
100
*etcd* using SSL authentication.


101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
Building from source
++++++++++++++++++++

To build autoradio from source, you should have a Go environment set
up properly on your machine. Autoradio uses godep_ to manage its
dependencies, so make sure you have that installed as well. Building
autoradio should then be as simple as running, from the top-level
source directory::

    $ godep go install ./...

This should install the ``radiod``, ``redirectord`` and ``radioctl``
executables in ``$GOPATH/bin``.


ale's avatar
ale committed
116
117
118
119
Operation
---------

In order to create a new stream (*mount*, in the Icecast terminology),
ale's avatar
ale committed
120
assuming you are running autoradio on the ``example.com`` domain:
ale's avatar
ale committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

#. On any node, run::

    $ radioctl create-mount /path/to/mount.ogg

   this will output the username and password used to authenticate the
   source. Take note of them.

   The cluster will be automatically reconfigured with the new mount in
   a few seconds at most.

#. Configure the source, using the username/password provided in the
   previous step, and point it at the following URL::

    http://stream.example.com/path/to/mount.ogg

#. Tell your users to listen to the stream at::

    http://stream.example.com/path/to/mount.ogg.m3u


DNS zone delegation
+++++++++++++++++++

Since we can't modify the DNS glue records for the zone delegation in
real-time, we have to restrict slightly the assumptions on the
availability of nodes in the cluster: you have to assume that at least
N of your nodes will be partially available at any one time (i.e. at
least one of a chosen subset of N servers will be reachable). The
number N should be fairly low, say 3. Then, you can use those 3
servers as the nameservers for zone delegation, and the other nodes
are free to have dynamic membership.


ale's avatar
ale committed
155
156
157
158
159
160
161
162
163
Firewalls
+++++++++

The users should be able to reach ports 53/tcp, 53/udp, 80/tcp and
8000/tcp on all nodes. Nodes should be able to reach 4001/tcp and
4002/tcp on each other; these two ports can be public if you've set up
X509-based authentication to etcd.


ale's avatar
ale committed
164
165
166
Instrumentation
+++++++++++++++

167
168
The ``radiod`` and ``redirectord`` daemons can send runtime metrics to
a *statsd* server (by default on localhost:8125).
ale's avatar
ale committed
169
170


ale's avatar
ale committed
171
172
173
174
175
176
177
178
179
180
181
182
Transcoding
+++++++++++

It is possible to set up a mount to relay an upstream mount re-encoded
with different parameters, using the ``radioctl
create-transcoding-mount`` command. In this case, autoradio will
automatically start up a process (a liquidsoap_ instance) to perform
the re-encoding, which will connect as the mount source. A
master-election protocol is used to ensure that only one such process
per mount is started in the whole cluster.


183
184
185
186
Testing
-------

There's a Vagrant_ configuration in the ``vagrant-test`` subdirectory
187
188
that will turn up a test three-node cluster (with Debian Wheezy as the
base system) using pre-packaged binaries. To run it::
189
190
191
192
193
194
195
196

    $ cd vagrant-test
    $ vagrant up

It will take a while to download the base image the first time, then
it will turn up three nodes called **node1**, **node2** and **node3**.
Use ``vagrant ssh`` to inspect them.

ale's avatar
ale committed
197
198

.. _etcd: https://github.com/coreos/etcd
ale's avatar
ale committed
199
.. _autoca: https://git.autistici.org/ai/autoca
200
.. _Vagrant: http://www.vagrantup.com/
201
.. _godep: https://github.com/tools/godep
ale's avatar
ale committed
202
.. _liquidsoap: http://savonet.sourceforge.net/