diff --git a/README b/README deleted file mode 100644 index 33e482ad3aad5fe642ad22961e24776c5783ddc0..0000000000000000000000000000000000000000 --- a/README +++ /dev/null @@ -1,7 +0,0 @@ - - -radio.ai -======== - -A distributed, fault-tolerant icecast streaming network. - diff --git a/README.rst b/README.rst new file mode 100644 index 0000000000000000000000000000000000000000..6b33fe29cc55a258e9e6f92adcd166b0daeaa455 --- /dev/null +++ b/README.rst @@ -0,0 +1,102 @@ + + +radio.ai +======== + +The RadioAI service aims to provide a reliable, fault-tolerant Icecast +streaming network 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. + +It is a full-stack service, meaning that it includes its own DNS and +HTTP servers, for full control of the request flow. + +RadioAI works by using etcd_ to coordinate the various nodes and store +the global mount configuration. The intended target is a set of +homogeneous servers (or virtual machines) dedicated to this purpose. +RadioAI also needs a dedicated DNS domain (or a delegation for a +subdomain). + + +Installation +------------ + +The simplest installation method is probably to use the pre-built +Debian packages (only available for amd64 at the moment), by placing +this line in ``/etc/apt/sources.list.d/radioai.list``:: + + deb http://www.incal.net/ale/debian radioai/ + +And then running:: + + $ sudo apt-get update + $ sudo apt-get install etcd radioai + +This will install and start the necessary jobs (which will initially +fail due to the missing configuration). + +Edit ``/etc/default/radioai`` and set, at least, the ``DOMAIN`` +variable to what you've assigned to the cluster. The jobs will +automatically start as soon as the configuration is saved. + + +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. + +Install the CA certificate in ``/etc/radioai/etcd_ca.pem``, the client +certificate in ``/etc/radioai/etcd_client.pem`` and its private key in +``/etc/radioai/etcd_client.key``, and the clients will connect to +*etcd* using SSL authentication. + + +Operation +--------- + +In order to create a new stream (*mount*, in the Icecast terminology), +assuming you are running RadioAI on the ``example.com`` domain: + +#. 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. + + + +.. _etcd: https://github.com/coreos/etcd +.. _autoca: https://git.autistici.org/public/ai/autoca diff --git a/cmd/redirectord/redirectord.go b/cmd/redirectord/redirectord.go index ccec7671798eba0a197a2c2e5723be439d41f5b6..f63c71ef80c28edea550705e8dd47a82c61139e3 100644 --- a/cmd/redirectord/redirectord.go +++ b/cmd/redirectord/redirectord.go @@ -15,8 +15,8 @@ var ( httpPort = flag.Int("http-port", 80, "HTTP port") publicIp = flag.String("ip", "127.0.0.1", "Public IP for this machine") - staticDir = flag.String("static-dir", "./static", "Static content directory") - templateDir = flag.String("template-dir", "./templates", "HTML templates directory") + staticDir = flag.String("static-dir", "/usr/share/radioai/htdocs/static", "Static content directory") + templateDir = flag.String("template-dir", "/usr/share/radioai/htdocs/templates", "HTML templates directory") // Default DNS TTL (seconds). dnsTtl = 5