Icecast 2.4.1 Dokumentáció

2. Változtatások (Changes)

Verzió 2.4.1

• Javítva a fájlleírók (file descriptor) keresztszennyeződése az on-connect/on-disconnect szkriptek által, különösen a STDIN, STDOUT és STDERR kapcsolatban a TCP-kapcsolatokkal.
• Most nemcsak a 0, 1 és 2 számú fájlleírót zárjuk le, hanem az első 1024-et — ez elterjedt kompromisszumos megoldás, de nem ideális. Alaposabb javításhoz platform-specifikus logikára és komoly munkára lesz szükség.
• A STDIN/OUT/ERR probléma megbízhatóan javítva, de más hibák előfordulhatnak, ha a szkript és a szerver egyszerre használ >1024-es FD-ket.
• Most már ésszerűen biztonságos, de továbbra is óvatosan kell használni.
• Az SSLv3 és az SSL tömörítés letiltva a biztonság javítása érdekében.
• Frissítve az alapértelmezett titkosítási beállítások biztonságosabbra.
• Javítva a JSON státusz API problémái.
• Az XSLT utolsó elemének ellenőrzése minden szűrt címkébe bekerült, így nem kell többé ezzel a hibával számolni, és egyszerűbb a testreszabás is.
• Javítva az <auth> működése a <mount type="default"> esetében.
• Javítva a hallgatói kapcsolat időtartamának naplózása az access.log-ban. Ez a regresszió korábban csak egyes platformokon jelent meg biztonsági javítás következtében.
• Javítva az időzóna-jelentés az _iso8601 mezőkben Windows alatt.
• Figyelmeztetések hozzáadva üres vagy alapértelmezett értékek esetén a <fileserve>, <hostname>, <location>, <admin> és <server-id> elemeknél.
• A hibanapló (loglevel WARN) a standard hibakimenetre (stderr) kerül a naplófájlok megnyitása előtt.
• Javítva az üres karakterláncok kezelése a konfigurációs fájlban — mostantól ez működik az accesslog, errorlog, logdir, webroot, adminroot, és remélhetőleg mindenféle port esetén is.
• Bővebb hibaüzenet adása, ha a fileserve ki van kapcsolva (sokan letiltják, majd csodálkoznak, hogy a webes felület CSS-e hibás formázást ad vissza).
• Részletesebb naplóüzenetek:
• Forrás IP cím hozzáadva az indítási és leállítási naplókhoz.
• Mountpoint hozzáadva néhány naplósorhoz.
• Frissítve a konfigurációs fájl, hogy elkerülje a gyakori buktatókat és érthetőbb legyen.
• Javítva néhány fordítási figyelmeztetés.
• Javítva az autogen.sh, hogy megfelelően működjön Mac OS alatt.
• Javítva a JSON hozzáférés: hozzáadva a globális és mount-specifikus egyéni HTTP-fejléc támogatása.
• Cél: a böngészőből történő JSON elérés támogatása alapvető CORS esetekben.
• Fontos HTML5 <audio> vagy <video> használati eseteknél, és a JSON státusz API elérésénél.
• Az alapértelmezett Icecast konfiguráció most tartalmazza a nagyon engedékeny globális fejlécet: <header name="Access-Control-Allow-Origin" value="*" />

• A HTTP PUT megvalósítás jelenleg nem támogatja a darabolt (chunked) kódolást.
• HTTP PUT “Expect: 100-Continue” esetén először „100”-at, majd nem sokkal utána „200”-at küld, ahelyett, hogy a „200” az átvitel végén érkezne.
• Az <on-connect> és <on-disconnect> használatánál kis eséllyel keveredhetnek a stream fájlleírók a szkript fájlleíróival, ha az FD számok meghaladják az 1024-et — ez a következő Icecast verzióban lesz teljesen javítva.
• Ne használj megjegyzéseket a <http-headers> szekcióban, mert megakadályozza a további <header> címkék feldolgozását.

Verzió 2.4.0

• Ogg Opus, WebM stream támogatás.
• HTTP 1.1 PUT támogatás forráskapcsolatokhoz, a SOURCE metódus elavult.
• Alapértelmezett mount: lehetőség globális beállítások definiálására minden mount számára (pl. URL-alapú autentikáció forrásoknak és hallgatóknak).
• Webes felület teljesen újratervezve (ePirat munkája), mobil eszközökön is jobb megjelenítés.
• <audio> elem hozzáadva a támogatott hangfolyamokhoz.
• Teljes XHTML 1.0 strict validáció.
• Alap JSON API (/status-json.xsl) XML→JSON sablon alapján (Doeke Zanstra munkája), kb. ugyanazt az adatot adja, mint a status.xsl.
• Karakterkészlet küldése HTTP-fejlécekben (kivéve file-serve és stream).
• strftime(3) %x kódok engedélyezése <dump-file>-ban (Win32 alatt tiltva).
• ISO8601 időbélyegek a statisztikákban (stream_start_iso8601, server_start_iso8601).
• Win32-re fordítható mingw segítségével.
• headers és header_prefix opciók URL-alapú hallgatói hitelesítéshez.
• Frissített listener_remove kezelő, ip= és agent= paraméterekkel.
• A master szerver teljes URL-eket is visszaadhat.

• Biztonsági javítás: kiegészítő csoportok felülbírálása.
• Versenyhelyzetek (race conditions) javítása.
• Debian csomagolási könyvtár eltávolítva (a Debian sajátot használ).
• Megfelelő HTTP fejlécek küldése kliensválaszokban.
• Content-Length fejléc javítása admin (raw) kéréseknél.
• Naplóbejegyzések escape-elése az access.log-ban.
• Memóriaszivárgás javítása stream fejlécvesztés miatt (rossz referencia számláló).
• Memóriaszivárgás elkerülése _parse_mount()-ban, ha a type attribútum be van állítva.
• Webfelület frissítése XHTML-kompatibilisre.
• status2.xsl eltávolítva (hibás példa volt).

• Összeomlik, ha bizonyos konfigurációs címkék üresek maradnak.

3. Alapbeállítás (Basic Setup)

Alapvető követelmények

Ez a rész leírja az egyszerű internetes rádióállomás beállításának alapvető követelményeit. Ez semmiképp sem egy teljes lista, de elegendő információt ad a kezdéshez.

Fontos megjegyezni, hogy ezek általános útmutatások. Ha egy Linux/Unix disztribúció csomagját telepítetted, akkor előfordulhat, hogy a könyvtárstruktúra, az indítás módja és egyéb részletek eltérnek. Ilyen esetben mindig olvasd el az adott disztribúció dokumentációját vagy specifikus útmutatóit (How-To).

A két fő összetevő

1. Streaming szerver – ebben az esetben az Icecast.
2. Forrás kliens (source client) – a tartalmat biztosító komponens.

Az Icecast szerver az a hely, ahová az összes hallgató csatlakozik. A forrás kliens általában külön gépen fut, mint az Icecast, de nem kötelező. A forrás kliens küldi az adatfolyamot (kódolt hangot) az Icecast szervernek, amely továbbítja azt a hallgatóknak.

Nem minden forrás kliens kompatibilis az Icecast 2-vel, ezért mindig ellenőrizd, hogy az általad választott kliens támogatja-e.

Alapfogalmak

Egy Icecast szerver több közvetítést (vagy mountpointot) is kiszolgálhat, melyek külön tartalomfolyammal rendelkeznek.

• A mountpoint egy egyedi név a szerveren, amely egy adott streamet azonosít – hasonlít egy fájlnévre, pl. /stream.ogg.
• Egy hallgató egyszerre csak egy mountpointhoz csatlakozhat.
• Egy Icecast szerver lehetővé teszi, hogy többféle tartalommal rendelkező közvetítéseket, vagy azonos tartalmat eltérő bitrátával/ minőséggel sugározz.

Ez a leírás a Unix és a Win32 konzolos verzióra vonatkozik. Az Icecast elérhető Win32 grafikus felülettel is, amely hasonló módon állítható be, de néhány lépés eltérhet.

Telepítés és alapbeállítás

Az első lépés az Icecast2 szerver beszerzése és telepítése. (A telepítési folyamat nem része ennek a dokumentumnak.) A telepítés után rendelkezned kell egy Icecast bináris állománnyal és három könyvtárral:

• conf – Tartalmazza az Icecast konfigurációs fájlt (icecast.xml), amely az összes beállítást meghatározza.
• admin – Az Icecast webes adminisztrációs felületéhez szükséges XSLT fájlokat tartalmazza.
• logs – Üres könyvtár, ahová (a konfigurációtól függően) a naplófájlok kerülnek.

Ezután szerkeszd az icecast.xml fájlt, és állítsd be a következő alapértékeket:

• <hostname> – DNS-név vagy IP-cím, amely a stream könyvtárlistákhoz használatos.
• <source-password> – A forrás kliens hitelesítéséhez használt jelszó.
• <admin-password> – Az adminisztrációs funkciók eléréséhez használt jelszó.
• <listen-socket> – A port és opcionálisan a bind-cím beállítása.

A szerver indítása

A konfiguráció mentése után a következő paranccsal indíthatod a szervert:

icecast -c /útvonal/icecast.xml

Ha nem jelenik meg hibaüzenet, ellenőrizd az error.log fájlban, hogy szerepel-e a „server started” üzenet, például:

[2003-10-31 13:04:49] INFO main/main.c Icecast 2.3.0 server started

A dátum, idő és fájlnév eltérhet, de a lényeg, hogy a szerver elindult, a naplózás működik, és a verziószám megjelenik.

Ezt úgy is ellenőrizheted, hogy felkeresed a következő URL-t:

http://<ip>:<port>/admin/stats.xml
vagy
http://<hostname>:<port>/admin/stats.xml

Felhasználónévként add meg: admin, jelszóként pedig az <admin-password> mezőben megadott értéket. Ha minden rendben, egy kis XML-fát fogsz látni, amely az Icecast statisztikáit mutatja.

A forrás kliens beállítása

A forrás klienshez szükséges információk:

• Icecast szerver IP-címe és portja(<listen-socket>)
• Forrás jelszó (<source-password>)

Emellett választanod kell egy mountpointot, és be kell állítanod a forrás kliensben.

• Ogg Vorbis streamek esetén mindig .ogg kiterjesztést használj (pl. /mystream.ogg).
• MP3 streameknél általában nincs kiterjesztés (pl. /mystream).
• Ne használj szóközt vagy speciális karaktereket a mountpoint nevében.

Stream hallgatása

Miután a forrás kliens csatlakozott az Icecast szerverhez, a hallgatás egyszerű: nyisd meg a következő URL-t böngészőben vagy médialejátszóban:

http://<ip>:<port>/<mountpoint>
vagy
http://<hostname>:<port>/<mountpoint>

Példa: ha a szerver címe 192.0.2.23:8000, a mountpoint pedig /mystream.ogg, akkor:

• Böngészőben: http://192.0.2.23:8000/mystream.ogg
• Lejátszólista formátumban (m3u): http://192.0.2.23:8000/mystream.ogg.m3u

Az .m3u link a legtöbb médialejátszóval automatikusan megnyitható, és nem csak MP3 streamet tartalmazhat, hanem bármilyen tartalomtípusú streamet is.

4. Konfigurációs fájl (Config File)

Figyelmeztetés

Kérjük, vedd figyelembe, hogy különösen az új Icecast felhasználók számára a konfigurációs fájl szerkesztése meglehetősen bonyolult lehet. Ezért ajánlott, hogy először készíts biztonsági másolatot az eredeti konfigurációs fájlról, majd csak a jelszavakat változtasd meg, mást ne. Ezután a source-password használatával elindíthatsz egy kezdeti streamet, és jobban megismerheted, hogyan működik az Icecast.

Ha testre kell szabnod a konfigurációt, akkor a módosítás előtt készíts biztonsági másolatot a működő konfigurációs fájlról.

Ha az Icecast nem hajlandó elindulni, annak legtöbbször egy hibás konfigurációs fájl az oka. Ilyen esetben a következő parancs futtatása általában megmutatja az XML szintaktikai hibák nagy részét:

xmllint icecast.xml

Továbbá ellenőrizd az Icecast error.log fájlt is további hibaüzenetekért!

Korlátozások

    <limits>
        <clients>100</clients>
        <sources>2</sources>
        <queue-size>102400</queue-size>
        <client-timeout>30</client-timeout>
        <header-timeout>15</header-timeout>
        ><source-timeout>10</source-timeout>
        <burst-on-connect>1</burst-on-connect>
        <burst-size>65536</burst-size>
    </limits>
    

Ez a rész a szerver szintű beállításokat tartalmazza, amelyeket általában nem szükséges megváltoztatni. Csak akkor módosítsd, ha pontosan tudod, mit csinálsz.

• clients
  

  A szerver által támogatott egyidejű kliensek (kapcsolatok) maximális száma. A hallgatók klienseknek számítanak, de a statikus tartalomhoz való hozzáférés (például kiszolgált fájlok) és a statisztikák lekérése is ide tartozik. Ez az érték a teljes szerverre vonatkozik, nem csak egy-egy mountpontra.

• sources
  

  A szerver által támogatott maximális forráskapcsolatok száma. Ide tartoznak az aktív relék és a forrás kliensek is.

• queue-size
  

  A stream sor maximális mérete bájtban. Ha egy hallgató a hálózati torlódás miatt átmenetileg lemarad, a szerver egy belső sort tart fenn számára. Ha ez a sor túllépi a beállított értéket, akkor az adatok levágásra kerülnek, és az érintett hallgatók megszakadnak a streamről.
  Ez alapértelmezetten 512 kB (ha itt nincs felülírva). Egyéni mount beállításban is megadható, például nagy sávszélességű videó és alacsony bitrátájú audio streamek keveréséhez.

• client-timeout
  

  Úgy tűnik, ez az opció nem kerül használatra.

• header-timeout
  

  A maximális idő (másodpercben), ameddig a szerver vár egy kérés beérkezésére, miután a kliens csatlakozott. Általában nincs szükség ennek módosítására.

• source-timeout
  

  Ha egy csatlakozott forrás nem küld adatot ezen idő (másodpercben) belül, a kapcsolat megszakad.

• burst-on-connect
  

  Ez tulajdonképpen a burst-size beállítás másik neve. Ha engedélyezve van, a burst mérete 64 kB, ha le van tiltva, akkor 0 kB. Ez az opció elavult, helyette a burst-size használandó.

• burst-size
  

  A kapcsolat létrejöttekor a kliensnek egyszerre elküldött adat mennyisége bájtban. Célja a médialejátszó pufferének gyors feltöltése. Alapértelmezett értéke 64 kB, amit általában nem szükséges módosítani. Ez minden mountpontra érvényes, hacsak nincs külön felülírva.
  Ügyelj rá, hogy kisebb legyen, mint a queue-size értéke, különben előfordulhat, hogy a kapcsolat a kezdeti burst miatt máris túllépi a queue méretét, ami a hallgatók kapcsolatának megszakadásához vezethet.

Hitelesítés

    <authentication>
        <source-password>hackme</source-password>
        <relay-user>relay</relay-user>
        <relay-password>hackme</relay-password>
        <admin-user>admin</admin-user>
        <admin-password>hackme</admin-password>
    </authentication>
    

Ez a rész tartalmazza az összes felhasználónevet és jelszót, amelyeket az adminisztrációhoz, valamint a források és relék csatlakoztatásához használnak.

• source-password
  

  A titkosítatlan jelszó, amelyet a források használnak az Icecast szerverhez való csatlakozáshoz. Az összes forráskapcsolat alapértelmezett felhasználóneve source, de ez az opció lehetővé teszi az alapértelmezett jelszó megadását.
  Ez és a felhasználónév az egyes mount szekciókban külön is módosítható.

• relay-user
  

  A mester szerveren kerül felhasználásra azonosítási célból, amikor egy slave szerver lekéri a közvetítendő streamek listáját.
  Az alapértelmezett felhasználónév: relay.

• relay-password
  

  A mester szerveren azonosításra használt jelszó, amikor egy slave szerver lekéri a közvetítendő streamek listáját.

• admin-user / admin-password
  

  Az adminisztrációs funkciókhoz használt felhasználónév/jelszó páros. Ez magában foglalja például a statisztikák lekérését, a webes adminisztrációs felülethez való hozzáférést stb.
  Az összes elérhető adminisztrációs funkció felsorolása a kézikönyv „Administration” fejezetében található.

Stream Könyvtár Beállítások

    <directory>
        <yp-url-timeout>15</yp-url-timeout>
        <yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
    </directory>
    

Ez a rész tartalmazza az összes beállítást, amelyek egy stream Icecast YP könyvtár-szervereken való megjelenítéséhez szükségesek.

Több directory szekció is megadható, ha több könyvtár-szerveren is szeretnéd listázni a streamet.

• yp-url-timeout
  

  Ez az érték adja meg, hogy az Icecast mennyi ideig várjon a választól az adott könyvtár-szerver felé küldött kérésnél. Az ajánlott érték általában elegendő a legtöbb könyvtár-szerver esetében.

• yp-url
  

  Az URL, amelyen keresztül az Icecast kommunikál a könyvtár-szerverrel. Ennek az értékét a könyvtár-szerver üzemeltetője adja meg.

Egyéb szerverbeállítások

Szerver szintű beállítások

    <hostname>localhost</hostname>
    <location>earth</location>
    <admin>icemaster@localhost</admin>
    <fileserve>1</fileserve>
    <server-id>icecast 2.4.1</server-id>
    

• hostname
  

  Ez az a DNS-név vagy IP-cím, amelyet a stream könyvtár lekérdezésekhez, illetve bizonyos esetekben a lejátszási listák előállításához használ a rendszer, ha a kliens nem ad meg Host fejlécet. Bár a példa itt localhost, a valóságban olyan címet kell beállítanod, amelyet a hallgatóid is tudnak használni.

• location
  

  Ez adja meg az adott Icecast példányhoz tartozó helyszín leírását. Például a webes felületen jelenik meg.

• admin
  

  Itt kell megadni a szerver adminisztrátorának elérhetőségét. Ez jellemzően egy e-mail cím, de mivel tetszőleges szöveg lehet, akár telefonszám is megadható. Szintén megjelenik például a webes felületen.

• fileserve
  

  Ez a kapcsoló engedélyezi az Icecast2 beépített fájlkiszolgálóját, amely statikus fájlokat tud kiszolgálni. Az összes fájl a <paths><webroot> konfigurációs beállításban megadott könyvtárhoz képest kerül kiszolgálásra. Alapértelmezésben be van kapcsolva, így elérhetők a státusz- és adminisztrációs oldalakhoz szükséges statikus fájlok (például képek és CSS-ek).

• server-id
  

  Ez az opcionális beállítás lehetővé teszi, hogy a rendszergazda felülírja a szerver alapértelmezett azonosítóját. Az alapértelmezett érték az icecast + verziószám (például icecast 2.4.1), és a legtöbb esetben nincs szükség ennek megváltoztatására. Nem javasolt módosítani, hacsak nincs rá nagyon nyomós indokod, és pontosan tudod, mit csinálsz.

TCP port beállítások

Az alábbiakban bemutatjuk, hogyan lehet megadni a szerver figyelési (listening) beállításait.

Általános portbeállítás

Az első példa egy egyszerű és gyakori módot mutat be egy figyelő socket meghatározására:

    <listen-socket>
        <port>8000</port>
    </listen-socket>
    

Ezt alapul véve bővíthetjük a beállítást egy <bind-address> opcióval, amely korlátozza, hogy az Icecast melyik IP-címen közvetítsen.
A legtöbb esetben nincs szükség a bind-address használatára, és gyakran okoz zavart, amikor indokolatlanul beállítják.

Egy másik lehetőség az <ssl> logikai beállítás, amely tájékoztatja az Icecastot arról, hogy biztonságos (titkosított) kapcsolatot kell használni.
Ennek tipikus felhasználási módja például az adminisztrációs oldal elérése HTTPS-en keresztül.

Visszafelé kompatibilitás Shoutcast forráskliensekkel

A következő példa azt mutatja meg, hogyan bővíthetünk egyetlen listen-socket-et úgy, hogy az a Shoutcast típusú forrás kliensekkel is működjön.

A Shoutcast klienseknél két probléma van az Icecast kliensekkel szemben:

1. nincs mountpontjuk,
2. két portot igényelnek.

Mindkét problémát egyszerűen meg lehet oldani egy kiegészítéssel a listen-socket-ben:

    <listen-socket>
        <port>8000</port>
        <shoutcast-mount>/live.mp3</shoutcast-mount>
    </listen-socket>
    

Mint korábban, a megadott port lefoglalásra kerül, de most a shoutcast-mount automatikusan meghatároz egy második figyelő socketet, amelynek portszáma mindig eggyel nagyobb, mint az itt megadott port.
Ez egyben tájékoztatja az Icecastot arról is, hogy a Shoutcast forrás kliens ezen a socketen melyik mountpontot fogja használni.

Ezzel a módszerrel egyszerre több Shoutcast kliens is csatlakozhat.

Régi típusú Shoutcast-kompatibilis beállítás (elavult)

Az alábbi példa a hosszabb módszert mutatja a Shoutcast kompatibilitás meghatározására:

    <shoutcast-mount>/live.nsv</shoutcast-mount>
    <!-- Több <listen-socket> elem is megadható -->
    <listen-socket>
        <port>8000</port>
    </listen-socket>

    <listen-socket>
        <port>8000</port>
        <shoutcast-compat>1</shoutcast-compat>
    </listen-socket>
    

Megjegyzés: Több listen-socket szekció is konfigurálható annak érdekében, hogy az Icecast több hálózati interfészen vagy több porton hallgasson.
Ha nincs bind-address megadva egy adott listen-socket-hez, akkor az socket az összes interfészhez kötődik (beleértve az IPv6-ot is, ha elérhető).

A legtöbb felhasználónak nincs szüksége bind-address megadására, és gyakran zavart okoz a használata.

• port
  

  A TCP port, amelyen a szerver elfogadja a klienskapcsolatokat.

• bind-address
  

  Egy opcionális IP-cím, amely segítségével a szervert egy adott hálózati kártyához köthetjük. Ha nincs megadva, akkor az összes interfészen hallgatni fog.

• ssl
  

  Ha az érték 1, akkor a listen-socket-en engedélyezve lesz a HTTPS. Ehhez az Icecastot openSSL támogatással kell fordítani.

• shoutcast-mount
  

  Egy opcionális mountpont beállítás, amely akkor használatos, amikor Shoutcast DSP-kompatibilis kliensek csatlakoznak. Az alapértelmezett globális érték /stream, de itt felülírható egy másik névvel, amely tartalmazhat kiterjesztést is (amit bizonyos kliensek megkövetelnek bizonyos formátumokhoz).
  
  Ha ez a beállítás egy listen-socket csoporton belül van megadva, akkor az Icecast tudja, hogy ez a port és a következő port a Shoutcast-kompatibilis forrás kliensekhez van fenntartva. Ez egy alternatív megoldás a shoutcast-compat helyett, mert implicit módon meghatározza a második portot is, és lehetővé teszi több különböző socket megadását eltérő mountpontokkal. Ha a shoutcast-mount a listen-socket csoporton kívül van, akkor globális beállításként működik.

• shoutcast-compat
  

  Ez az opcionális jelző azt mutatja, hogy az adott port Shoutcast kompatibilis módban fog működni. A forrás kliens protokollban meglévő jelentős különbségek miatt, ha bármelyik Shoutcast DJ eszközt használni szeretnéd, legalább egy socketet Shoutcast-kompatibilisnek kell konfigurálni.
  
  Fontos: ebben a módban csak a forrás kliensek (és kifejezetten a Shoutcast forrás kliensek) tudnak csatlakozni ehhez a porthoz. A hallgatók továbbra is csatlakozhatnak bármely más porthoz, amely nincs Shoutcast-kompatibilisre állítva.
  
  A teljes Shoutcast DSP kompatibilitás érdekében meg kell adni egy olyan listen-socket-et, amelynek portja eggyel kisebb a Shoutcast-kompatibilis portnál. Példa: ha a 8001-es port Shoutcast-kompatibilis, akkor szükség van egy 8000-es listen portra is, amely nem lehet Shoutcast-kompatibilis. További példákért lásd a disztribúcióhoz mellékelt konfigurációs fájlt.

Globális HTTP fejlécek

    <http-headers>
        <header name="Access-Control-Allow-Origin" value="*" />
        <header name="X-Robots-Tag" value="index, noarchive" />
        <header name="foo" value="bar" status="200" />
        <header name="Nelson" value="Ha-Ha!" status="404" />
    </http-headers>
    

Az Icecast beállítható úgy, hogy egyedi HTTP fejléceket küldjön. Ez elérhető globális beállításként, valamint az egyes mountpontokon belül is.

Ez a rész a globális beállításokat magyarázza el.

Ennek a funkciónak a bevezetésére főként azért került sor, hogy egyszerűbbé váljon a cross-origin resource sharing (CORS) használata.

Az Icecast alapértelmezett konfigurációja tartalmazza is az első fejlécet (lásd a fenti példában), éppen ezért.

• http-headers
  

  Ez az elem az Icecast konfiguráció fő szekcióján belül bárhová elhelyezhető. Gyermekelemei a <header> tagek, amelyek sorban meghatározzák a tényleges HTTP fejléceket.

• header
  

  Ez a tag adja meg azt a konkrét fejlécet, amelyet az Icecast minden HTTP kliensnek visszaküld a kérésekre adott válaszban.
  A következő attribútumokat tartalmazhatja:

• name (kötelező) – a HTTP fejléc mező neve.
• value (kötelező) – a HTTP fejléc mező értéke.
• status (opcionális) – korlátozza, hogy a fejléc csak bizonyos HTTP státuszkódok esetén kerüljön elküldésre.
  Ha nincs megadva, akkor a fejléc minden HTTP státuszkód esetén visszaküldésre kerül.
  Ez az attribútum jelenleg csak a globális fejléceknél használható.

Jelenleg csak a globális fejlécek kerülnek elküldésre akkor, ha a HTTP státusz nem 200. Ez a jövőben változhat. Ne helyezz megjegyzéseket (<!-- ... -->) a <http-headers> szekcióba, mert ebben a verzióban az Icecast nem tudja majd feldolgozni a további <header> tageket.

Streamek továbbítása

Ez a rész a szerver relay (továbbítási) beállításait tartalmazza.

A relézés egy pull (lehívásos) rendszeren keresztül működik, ahol a fogadó szerver úgy csatlakozik a küldő szerverhez, mintha hallgató lenne.

Kétféle relay beállítás létezik:

• Mester szerver relé (Master server relay)
• Konkrét mountpont relé (Specific Mountpoint relay)

Mester Relé (Master Relay)

A mester szerver relé kizárólag Icecast szerverek között támogatott, és célja több mountpont továbbítása egy távoli Icecast szerverről.

    <master-server>127.0.0.1</master-server>
    <master-server-port>8001</master-server-port>
    <master-update-interval>120</master-update-interval>
    <master-username>relay</master-username>
    <master-password>hackme</master-password>
    <relays-on-demand>0</relays-on-demand>
    

A következő ábra bemutatja a mester relé használatának alapjait.

Fontos: a slave szerver van konfigurálva a <master-server>, <master-server-port>, stb. beállításokkal. A master az az Icecast szerver, ahonnan a slave lehívja és továbbítja a mountpontokat.
Mester relé használatával az összes nem rejtett mountpont a master szerveren továbbítható ezzel a módszerrel.

Beállítások magyarázata

• master-server
  

  A master szerver IP címe, amely a továbbítandó mountpontokat tartalmazza.

• master-server-port
  

  A master szerver TCP portja, amely a továbbítandó mountpontokat tartalmazza.

• master-update-interval
  

  Az az időköz (másodpercben), amilyen gyakran a slave (relay szerver) lekérdezi a master szervert új mountpontok után.

• master-username
  

  A relay felhasználónév a master szerveren. Ezzel lehet a mountpontok listáját lekérdezni.
  Ha nincs megadva, az alapértelmezett a relay.

• master-password
  

  A relay jelszó a master szerveren. Ezzel lehet a mountpontok listáját lekérdezni.

• relays-on-demand
  

  Globális beállítás a relézéshez.
  Mivel a mester relé esetén nincs egyéni relay opció, előfordulhat, hogy azt szeretnéd, hogy a relay csak akkor húzza le a streamet, ha van hallgató a slave oldalon.
  Ez tipikus eset például a felesleges sávszélességi költségek elkerülésére, amikor senki sem hallgatja a streamet.

Konkrét Mountpont Relé (Specific Mountpoint Relay)

Ha csak bizonyos mountpontokat kell továbbítani, akkor az Icecast beállítható „Specific Mountpoint Relay”-ként.

A következő ábra egy specifikus csatolási pont relé használatának alapjait mutatja be. Vedd figyelembe, hogy a továbbító Icecast a <relay> beállításokkal van konfigurálva, és lekéri a megadott csatolási pont(oka)t, majd továbbítja azokat a hallgatóknak. Egy specifikus csatolási pont relé használatával csak a megadott csatolási pontok kerülnek továbbításra.

Az adott csatolási pont relék konfigurálhatók úgy, hogy Icecast 2 szerverről, valamint Icecast 1.x és Shoutcast szerverről továbbítsanak. Egy szervert úgy lehet specifikus csatolási pont szerver reléként konfigurálni, hogy minden továbbítandó csatolási ponthoz megadunk egy <relay> XML darabot a konfigurációs fájlban. A továbbított szervernek nincs szüksége semmilyen speciális konfigurációra.

    <relay>
        <server>127.0.0.1</server>
        <port>8001</port>
        <mount>/example.ogg</mount>
        <local-mount>/different.ogg</local-mount>
        <username>joe</username>
        <password>soap</password>
        <relay-shoutcast-metadata>0</relay-shoutcast-metadata>
        <on-demand>1</on-demand>
    </relay>
    

Beállítások magyarázata

• server
  

  Annak a szervernek az IP címe, amely a relézendő mountpontot tartalmazza.

• port
  

  Annak a szervernek a TCP portja, amely a relézendő mountpontot tartalmazza.

• mount
  

  A távoli szerveren található mountpont neve.
  Ha Shoutcast streamet relézel, akkor ez legyen / vagy /name.

• local-mount
  

  A helyi mountpont neve. Ez lesz a relay szerveren a stream neve.
  Ha nincs megadva, akkor az eredeti (távoli) mountpont nevét használja.

• username
  

  Ha a relézett forrás hitelesítést igényel, itt adható meg a felhasználónév.

• password
  

  Ha a relézett forrás hitelesítést igényel, itt adható meg a jelszó.

• relay-shoutcast-metadata
  

  Ha Shoutcast streamet relézel, itt adható meg, hogy a Shoutcast adatfolyamból származó metaadatokat (például dalcímeket) is továbbítsa-e.

• 1: engedélyezve
• 0: letiltva
• on-demand
  

  Az on-demand relay csak akkor húzza (kéri) le a streamet, ha van hallgató, aki kéri.

• 1: engedélyezve
• 0: letiltva (alapértelmezett: <relays-on-demand> értéke).
  Ez hasznos, ha sávszélességet szeretnél megtakarítani, amikor épp nincs hallgató.

Mount specifikus beállítások

    <mount type="normal">
        <mount-name>/example-complex.ogg</mount-name>
        <username>othersource</username>
        <password>hackmemore</password>
        <max-listeners>1</max-listeners>
        <max-listener-duration>3600</max-listener-duration>
        <dump-file>/tmp/dump-example1.ogg</dump-file>
        <intro>/intro.ogg</intro>
        <fallback-mount>/example2.ogg</fallback-mount>
        <fallback-override>1</fallback-override>
        <fallback-when-full>1</fallback-when-full>
        <charset>ISO8859-1</charset>
        <public>1</public>
        <stream-name>My audio stream</stream-name>
        <stream-description>My audio description</stream-description>
        <stream-url>http://some.place.com</stream-url>
        <genre>classical</genre>
        <bitrate>64</bitrate>
        <type>application/ogg</type>
        <subtype>vorbis</subtype>
        <hidden>1</hidden>
        <burst-size>65536</burst-size>
        <mp3-metadata-interval>4096</mp3-metadata-interval>
        <authentication type="xxxxxx">
            <!-- Lásd a hallgatói hitelesítés dokumentációját -->
        </authentication>
        <http-headers>
            <header name="Access-Control-Allow-Origin" value="*" />
            <header name="X-Robots-Tag" value="index, noarchive" />
            <header name="foo" value="bar" status="200" />
            <header name="Nelson" value="Ha-Ha!" status="404" />
        </http-headers>
        <on-connect>/home/icecast/bin/source-start</on-connect>
        <on-disconnect>/home/icecast/bin/source-end</on-disconnect>
    </mount>
    

Ez a rész azokat a beállításokat tartalmazza, amelyek csak egy adott mountpontra vonatkoznak, és alkalmazandók egy bejövő streamre, legyen az relay vagy forrás kliens.
A mount definíció célja, hogy bizonyos információkat megadjon, amelyek felülírhatják a globális/alapértelmezett beállításokat vagy a bejövő stream által szolgáltatott adatokat.

Egy mountot nem kötelező megadni minden bejövő forráshoz, de előfordulhat, hogy szeretnél például egyedi felhasználónév/jelszó párost, vagy hallgatószám-limitet beállítani.
Általános szabály: csak azt definiáld, amire szükséged van, de minden mount definíciónak tartalmaznia kell legalább a mount-name-t.

A legtöbb beállítás módosítása a konfigurációs fájl újratöltése után is érvénybe léphet aktív streameknél, viszont van, ami csak a stream indulásakor vagy leállásakor.

Beállítások magyarázata

• type
  

  A mount típusát adja meg (alapértelmezés: normal).
  Ha default típusú mountot hozol létre, azzal több mount számára tudsz közös értékeket megadni.
  Fontos: a default mount nem keveredik más mount blokkokkal – csak akkor érvényes, ha nincs az adott mountponthoz tartozó normal típus.

• mount-name
  

  A mountpont neve, amelyre ezek a beállítások vonatkoznak. default típus esetén nem használható.

• username / password
  

  Opcionális értékek, amelyek meghatározzák, hogy a forrás milyen felhasználónévvel/jelszóval csatlakozhat.
  Ha nincs megadva, alapértelmezett a source felhasználónév és a globális source-password.

• max-listeners
  

  Maximális hallgatószám az adott mountpontra.

• max-listener-duration
  

  A maximális idő (másodpercben), ameddig egy hallgató kapcsolódva maradhat. Hitelesítés esetén ezt felül lehet írni.

• dump-file
  

  Opcionális fájlnév, amelybe az adott mountpontról érkező stream lementésre kerül.
  A fájlnévben használhatók dátum/idő változók a strftime() függvénynek megfelelően (pl. %F).

• intro
  

  Fájl, amelyet az újonnan csatlakozó hallgatók hallanak, mielőtt az élő stream elindulna.
  A fájl formátumának egyeznie kell a stream formátumával.

• fallback-mount
  

  Olyan mountpontot ad meg, ahova a hallgatók automatikusan átkerülnek, ha a forrás leáll vagy nem elérhető.

• Csak egy fallback adható meg mountonként.
• Lehet másik mountpont, vagy webrootban lévő fájl (pl. előre rögzített üzenet lejátszására).
• Többszintű fallback is lehetséges (egy mount átirányíthat másik mount fallbackjére).
• fallback-override
  

  Engedélyezve: ha egy új forrás csatlakozik, a hallgatók automatikusan visszakerülhetnek a fallbackről az élő streamre.

• fallback-when-full
  

  Ha értéke 1, és a mountpont elérte a maximális hallgatószámot, az új hallgatók automatikusan a fallback mountpontra kerülnek.

• charset
  

  Főleg MP3 streameknél releváns. Meghatározza a metaadat karakterkódolását (pl. ISO8859-1).
  Alapértelmezett: Latin1, de megadható UTF-8 vagy más is.

• public
  

  Meghatározza, hogy a mount hirdetve legyen-e a YP könyvtárban.

• -1: a forrás dönti el
• 0: nem hirdeti
• 1: kötelező hirdetni
• stream-name / stream-description / stream-url / genre / bitrate / type / subtype
  

  Ezek opcionális mezők, amelyekkel a streamhez metaadatokat adhatsz meg (pl. név, leírás, műfaj, bitráta, MIME-típus).
  Akkor is felülírják a statisztikákban megjelenő adatokat, ha a forrás már biztosít információt.

• hidden
  

  Ha engedélyezve van, a mount nem jelenik meg az admin XSL oldalakon. Főleg relék esetén hasznos.

• burst-size
  

  Felülírhatja a globális burst-size beállítást. Értéke bájtban.

• mp3-metadata-interval
  

  Shoutcast kompatibilis stream esetén megadhatod, hány bájtonként legyen metaadat frissítés.

• authentication
  

  Megadható hallgatói (vagy forrás) hitelesítés. Támogatott: fájl alapú (htpasswd), vagy URL alapú.

• http-headers
  

  HTTP fejléc hozzáadása a válaszokhoz erre a mountpontra.
  Például:

    <header name="Access-Control-Allow-Origin" value="*" />
    

• on-connect / on-disconnect
  

  Programot ad meg, amely lefut a forrás indulásakor / leállásakor.
  Paraméterként megkapja a mountpont nevét.
  (Figyelem: Win32 alatt nem támogatott!)

Útvonal beállítások

    <paths>
        <basedir>./</basedir>
        <logdir>./logs</logdir>
        <pidfile>./icecast.pid</pidfile>
        <webroot>./web</webroot>
        <adminroot>./admin</adminroot>
        <allow-ip>/path/to/ip_allowlist</allow-ip>
        <deny-ip>/path_to_ip_denylist</deny-ip>
        <ssl-certificate>/path/to/certificate.pem</ssl-certificate>
        <ssl-allowed-ciphers>
        ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:
        ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:
        RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS
        </ssl-allowed-ciphers>
        <alias source="/foo" dest="/bar"/>
    </paths>
    

Ez a szekció az Icecast által különböző célokra használt elérési útvonalakat tartalmazza.
Minden útvonal (kivéve az aliasokat) nem végződhet „/” jellel.

• basedir
  

  Ezt az elérési utat a chroot beállításokkal együtt használja a szerver. Meghatározza az alapkönyvtárat, amelyhez a szerver indításkor chroot-ol.
  Ez a funkció Win32 rendszeren nem támogatott.

• logdir
  

  Ez az útvonal adja meg a naplózás alapkönyvtárát. Az error.log és access.log fájlok ebben a könyvtárban jönnek létre.

• pidfile
  

  Ez az elérési út határozza meg azt a fájlt, amelybe a szerver induláskor beírja, majd normál leállításkor eltávolítja a saját folyamatazonosítóját (PID).
  Ez a fájl olvasható, és felhasználható például jelek (signals) küldésére az Icecast folyamatnak.

• webroot
  

  Az alapkönyvtár, amelyet minden statikus fájlkérés kiszolgálására használ a szerver. Ez a könyvtár tartalmazhat bármilyen szabványos fájltípust (például MP3 vagy Ogg Vorbis fájlokat).
  Példa: ha a webroot értéke /var/share/icecast2, és érkezik egy kérés http://server:port/mp3/stuff.mp3 címre, akkor a szerver a következő fájlt szolgálja ki: /var/share/icecast2/mp3/stuff.mp3.

• adminroot
  

  Ez az elérési út adja meg az adminisztrációs kérések alapkönyvtárát.
  Itt találhatók azok az XSLT scriptek, amelyeket a webes adminfelület használ. Az Icecast csomagban található admin könyvtár tartalmazza ezeket a fájlokat.

• allow-ip
  

  Ha meg van adva, akkor egy olyan fájl helyére mutat, amely IP-címek listáját tartalmazza. Csak ezekről az IP-címekről engedélyezett a csatlakozás az Icecast szerverhez.
  Ez akkor hasznos, ha például egy mester szerver csak ismert slave-eket szolgál ki.
  A fájl formátuma egyszerű: minden sor egy IP-címet tartalmaz.

• deny-ip
  

  Ha meg van adva, akkor egy olyan fájl helyére mutat, amely azonnal blokkolandó IP-címek listáját tartalmazza.
  Ez főleg problémás kliensek kizárására szolgál, amikor nincs hozzáférésed a tűzfal beállításaihoz.
  A fájl formátuma ugyanaz: minden sor egy IP-címet tartalmaz.

• ssl-certificate
  

  Ha meg van adva, akkor egy olyan fájl elérési útját tartalmazza, amelyben benne van az X.509 privát és publikus kulcs is. Ez szükséges a HTTPS támogatás engedélyezéséhez.
  Fontos: az az operációs rendszer felhasználó, amely alatt az Icecast fut, képes legyen olvasni ezt a fájlt. Ellenkező esetben „Invalid cert file” figyelmeztetés jelenik meg, mintha a fájl nem is létezne.

• ssl-allowed-ciphers
  

  Ez az opcionális címke az engedélyezett titkosítási algoritmusok listáját adja meg, amelyeket az SSL könyvtár használhat.
  Az Icecast alapértelmezésként tartalmaz egy beállítást, amely megfelel az aktuális legjobb gyakorlatoknak.
  Csak akkor módosítsd ezt, ha pontosan tudod, mit csinálsz.

• alias
  

  Az aliasok lehetővé teszik, hogy több mountpont ugyanarra a mountpontra mutasson.
  Például: <alias source="/foo" dest="/bar">

Naplózási beállítások

    <logging>
        <accesslog>access.log</accesslog>
        <errorlog>error.log</errorlog>
        <playlistlog>playlist.log</playlistlog>
        <loglevel>4</loglevel> <!-- 4 Debug, 3 Info, 2 Warn, 1 Error -->
    </logging>
    

Ez a rész az Icecast naplózásával kapcsolatos beállításokat tartalmazza. Az Icecast jelenleg három naplófájlt hoz létre:

• error.log – minden naplóüzenet ide kerül,
• access.log – ide kerülnek a stream/admin/HTTP kérések naplóbejegyzései,
• playlist.log – opcionális, lejátszási lista naplófájl.

Megjegyzés: nem Windows (non-win32) rendszereken az Icecast számára küldhető egy HUP jelzés, aminek hatására a naplófájlok újra megnyílnak append (hozzáfűzés) módban. Így lehetőség nyílik a naplófájlok áthelyezésére vagy eltávolítására futás közben.

Ha bármelyik naplófájl nevét egy kötőjelre állítod (pl. <accesslog>-</accesslog>), akkor az Icecast a fájl helyett a STDERR kimenetre fogja írni a naplókat.

• accesslog
  

  Ebbe a fájlba kerül minden kérés, amit az Icecast2 felé intéznek.
  Az elérési útvonal a <logdir> konfigurációs értékhez képest relatív.

• errorlog
  

  Minden Icecast által generált naplóüzenet ebbe a fájlba íródik.
  Ha a loglevel túl magasra van állítva (például Debug), akkor ez a fájl idővel elég nagyra nőhet.
  Jelenleg nincs beépített naplóforgatás (log-rotation).

• playlistlog
  

  Ebbe a fájlba kerül minden egyes mountponthoz tartozó metaadat-napló.
  A napló formátuma a jövőben változhat, amint kialakul egy szabványos formátum.
  Jelenleg a fájl „pipe-delimited” (| jellel elválasztott).
  Ez egy opcionális beállítás, a konfigurációs fájlból akár teljesen el is hagyható.

• logsize
  

  Ez az érték (Kbyte-ban) adja meg a naplófájlok maximális méretét.
  Ha egy naplófájl nagyobbra nő ennél, az Icecast vagy átnevezi logfile.old-ra, vagy ha a logarchive engedélyezve van, akkor időbélyeget ad a mentett fájl nevéhez.

• logarchive
  

  Ha engedélyezve van, az Icecast a naplófájlhoz időbélyeget fűz, amikor az eléri a logsize értéket.
  Ha nincs engedélyezve, akkor a naplófájlt egyszerűen logfile.old-ra nevezi át (felülírva a korábbi mentett naplót).
  Alapértelmezés szerint ki van kapcsolva, hogy elkerüljük a fájlrendszer betelését olyan felhasználóknál, akik nem figyelik a naplóik méretét.

• loglevel
  

  Meghatározza, hogy milyen üzenetek kerülnek naplózásra az Icecast-ban.
  Az üzenetek 4 kategóriába sorolhatók: Debug, Info, Warn, Error.
  Beállítási lehetőségek:

• loglevel = 4 → Debug, Info, Warn, Error üzenetek naplózása
• loglevel = 3 → Info, Warn, Error üzenetek naplózása
• loglevel = 2 → Warn, Error üzenetek naplózása
• loglevel = 1 → Csak Error üzenetek naplózása

Biztonsági beállítások

    <security>
        <chroot>0</chroot>
        <changeowner>
            <user>nobody</user>
            <group>nogroup</group>
        </changeowner>
    </security>
    

Ez a rész olyan konfigurációs beállításokat tartalmaz, amelyekkel az Icecast szerver biztonságát lehet növelni.
Ez történhet például egy chroot végrehajtásával egy biztonságos könyvtárba, vagy azzal, hogy a szerver indításakor megváltoztatjuk a futtató felhasználót és csoportot.

Az utóbbi módszer lehetővé teszi, hogy az Icecast olyan privilégizált portokhoz (pl. 80 és 443) kapcsolódjon, amelyekhez általában root jogosultság szükséges. Ilyenkor a szerver root-ként indul, lefoglalja a szükséges portokat, majd átvált a megadott felhasználóra/csoportra. Ez a funkció Windows (Win32) rendszeren nem támogatott.

• chroot
  

  Egy jelző, amely meghatározza, hogy a szerver indulásakor végrehajtódjon-e a chroot() hívás.
  A chroot-olt útvonalat a <basedir> konfigurációs érték határozza meg.
  A chroot beállítása és használata haladó szintű téma, és ennek a dokumentumnak nem része.

• changeowner
  

  Ez a rész adja meg azt a felhasználót és csoportot, amelyhez az Icecast folyamat tartozni fog, miután elindult.
  Ezeknek a rendszerben létező, érvényes felhasználóknak/csoportoknak kell lenniük.
  Fontos: ehhez az Icecastot root-ként kell indítani, különben nem működik.

5. Adminisztrációs felület (Admin Interface)

Áttekintés

Ez a rész az Icecast adminisztrációs felületéről tartalmaz információkat. Ezen a felületen keresztül a felhasználó számos szerverfunkciót kezelhet. Innen lehet statisztikákat lekérni, hallgatókat egyik mountpontról a másikra áthelyezni, csatlakozott forrásokat bontani, hallgatókat lekapcsolni, valamint sok más műveletet is végrehajtani.

Az összes funkció itt van felsorolva, valamint mindegyikhez található példa a használatára.

Minden funkció HTTP-hitelesítést igényel a megfelelő felhasználónévvel és jelszóval.

• Mountponthoz kötődő funkciók esetében használhatod az <admin-username> és <admin-password> értékeket, amelyeket az Icecast konfigurációs fájlban adtál meg, vagy az adott mountponthoz tartozó felhasználónevet és jelszót (ha van ilyen).
• Általános (nem egy adott mountponthoz tartozó) funkciók esetén viszont mindig az admin felhasználónevet és jelszót kell használnod.

Fontos megjegyezni, hogy minden példában a freestream.hu szerepel mint példa hoszt, és a 8240 (http) mint az Icecast szerver példaportja. Ezeket ne felejtsd el módosítani a saját szerver adataidra.

Adminisztrációs funkciók (mount specifikus)

Minden itt leírt adminisztrációs funkció mountponthoz kötött, vagyis csak egy adott mountpontra vonatkozik (nem az egész szerverre). Az összes ilyen funkció bemenetként megköveteli egy mountpont megadását.

Metaadat frissítés

Ez a funkció lehetővé teszi, hogy egy forrás kliens vagy bármely külső program frissítse egy adott mountpont metaadatait.

    http://freestream.hu:8240/admin/metadata?mount=/mystream&mode=updinfo&song=ACDC+Back+In+Black
    

Fallback frissítés

Ez a funkció lehetővé teszi, hogy egy forrás kliens vagy bármely külső program frissítse egy adott mountpont fallback mountpontját.

A fallback mountpontra kerülnek a hallgatók abban az esetben, ha a forrás kliens megszakad. Ha tehát a forrás kliens valamilyen okból lecsatlakozik, az összes aktuális hallgató automatikusan átirányításra kerül a fallback mountpontra.

    http://freestream.hu:8240/admin/fallbacks?mount=/mystream.ogg&fallback=/myfallback.ogg
    

Kliensek listázása

Ez a funkció kilistázza az összes, az adott mountponthoz jelenleg csatlakozó klienst. Az eredmény XML formátumban érkezik vissza.

    http://freestream.hu:8240/admin/listclients?mount=/mystream.ogg
    

Kliensek (hallgatók) áthelyezése

Ez a funkció lehetővé teszi a jelenleg csatlakozott hallgatók áthelyezését egyik mountpontról egy másikra. Ehhez két mountpontot kell megadni:

• mount → ahonnan a hallgatók átkerülnek
• destination → ahova a hallgatók átkerülnek

A kérés feldolgozása után minden hallgató, aki a mount-on volt, a destination-re kerül át.
Fontos, hogy a destination mountpontnak már léteznie kell, és egy forrás kliensnek adatot kell szolgáltatnia oda.

    http://freestream.hu:8240/admin/moveclients?mount=/mystream.ogg&destination=/mynewstream.ogg
    

Kliens (hallgató) bontása

Ez a funkció lehetővé teszi egy adott hallgató leválasztását az adott mountpontról.
A hallgatók egyedi azonosítóval (id) rendelkeznek, amelyet a Kliensek listázása funkcióval lehet lekérni.
Ezt az id-t kell megadni a kérésben. A kérés feldolgozása után az adott hallgató többé nem lesz csatlakoztatva a mountponthoz.

    http://freestream.hu:8240/admin/killclient?mount=/mystream.ogg&id=21
    

Forrás bontása

Ez a funkció lehetővé teszi egy adott mountpont forrásának lekapcsolását a szerverről.
A bontandó mountpontot a mount változóval kell megadni.

    http://freestream.hu:8240/admin/killsource?mount=/mystream.ogg
    

Adminisztrációs funkciók (általános)

Statisztikák (Stats)

A statisztika funkció lehetőséget biztosít arra, hogy lekérdezzük az Icecast szerver által tárolt belső statisztikákat.
Szinte minden információ elérhető a szerver működéséről ezen keresztül, például:

• milyen mountpontok vannak csatlakoztatva,
• hány klienskérést szolgált ki a szerver,
• mountpontonként hány hallgató van, stb.

Fontos megjegyezni, hogy ez az admin funkció elérhető a következő URL-szintaxissal is:

    http(s)://server:port/admin/stats.xml
    

Viszont ezt a szintaxist nem ajánlott használni, mivel idővel elavulttá válik és el lesz távolítva!

    http://freestream.hu:8240/admin/stats
    

Mountok listázása (List Mounts)

Ez a funkció lehetővé teszi, hogy megtekintsük az összes éppen csatlakoztatott mountpontot.

    http://freestream.hu:8240/admin/listmounts
    

Webalapú adminisztrációs felület

Ahelyett, hogy kézzel hívnánk meg az adminisztrációs URL-eket, egy webalapú adminisztrációs felület is készült. Ez a felület ugyanazokat a funkciókat biztosítja, amelyeket fentebb azonosítottunk és leírtunk, csak egy kicsit kényelmesebb formában.

Az Icecast-hoz tartozó webalapú admin felület az admin könyvtárban található, és azonnal használatra kész. A felhasználónak mindössze annyi a dolga, hogy a konfigurációs fájlban beállítja ennek a könyvtárnak az elérési útját az <adminroot> változó segítségével.

A webes adminisztrációs felület XSLT fájlok sorozatából áll, amelyek az URL alapú adminisztrációs felületen keresztül elérhető XML-adatokat jelenítik meg. Ezek a fájlok igény szerint módosíthatók. A változtatásokhoz azonban szükséges némi XSLT-ismeret, valamint az XML → HTML transzformációk megértése.

    http://freestream.hu:8240/admin/stats.xsl
    

Ezen az URL-en keresztül az összes adminisztrációs funkció elérhető.

• Az /admin könyvtárban lévő meglévő XSLT fájlok módosítása engedélyezett, de új fájlokat létrehozni itt nem lehet.
• Új XSLT fájlok létrehozása és meglévők módosítása a /web könyvtárban engedélyezett. Ezek az /admin/stats.xml által visszaadott dokumentummal dolgoznak.

Ha látni szeretnéd azt az XML dokumentumot, amelyet egy admin XSLT fájl feldolgoz, egyszerűen távolítsd el a .xsl kiterjesztést a kérésből (például: /admin/listclients). Ezután az így kapott XML alapján megírhatod a saját XSLT transzformációdat.

6. Szerver statisztikák (Server Statistics)

Áttekintés

Az Icecast kiterjedt futásidejű statisztikákat biztosít. Ezek egyrészt az aktuális kapcsolatok számát, másrészt az összesített számlálókat tartalmazzák (a szerver indítása óta, illetve egy-egy forrás csatlakozásának kezdete óta).

Adminisztrációs funkciók (mount specifikus)

Minden itt leírt adminisztrációs funkció mountponthoz kötött, vagyis csak egy adott mountpontra vonatkozik (nem az egész szerverre). Az összes ilyen funkció bemenetként megköveteli egy mountpont megadását.

HTML felület, XSLT által generálva

Az Icecast tartalmaz egy alapvető, XHTML alapú webes felületet. Ez a felület a szerver statisztikáinak egy alapvető részét teszi elérhetővé, ami a legtöbb felhasználói igényt kielégíti. Amennyiben szükséges, a web-root mappában található fájlok testreszabhatók úgy, hogy több vagy kevesebb információt tartalmazzanak (lásd a nyers XML adatok szakaszát alább).

Erősen ellenjavalljuk az adatok kinyerését („scraping”) a webes felületről, mivel azt nem tekintjük API-nak, és bármelyik verzióban megváltoztathatjuk, akár teljesen is!
Az előnyben részesített módszerek az egyedi XSLT, JSON és nyers XML.

Gép által olvasható adatok, XSLT által generálva

Az Icecast a rendkívül erős libXSLT motort használja arra, hogy a belső, nyers statisztikai adatokat egyedi igényekre szabott felületekké alakítsa.
Sokan írtak egyedi XSLT kódokat, amelyek például egyszerű szöveges „most játszott” listát, XSPF-et, VCLT-t, munin felülethez való adatokat stb. állítanak elő.

JSON API (2.4.0-tól)

Az Icecast 2.4.0-s verziójától kezdve tartalmaz egy alapvető JSON API-t (/status-json.xsl), amely Doeke Zanstra xml2json sablonjára épül (lásd: xml2json.xslt).íbr>Ez egy alap statisztikai adatkészletet tesz közzé, amely a legtöbb felhasználói igényt kielégíti.

A cél, hogy a jövőben ne szakadjon meg a visszafelé kompatibilitás ennél a felületnél, ugyanakkor azt javasoljuk, hogy a szoftvereket robusztus módon tervezzék meg, hogy kezelni tudják az esetleges változásokat, például változók hozzáadását vagy eltávolítását.

Elérhető nyers adatok

Ez a rész tartalmazza az Icecast-ban elérhető nyers XML szerver-statisztikai adatokat. Egy példastatisztikai XML-fát mutatunk be, és minden elem külön leírásra kerül.
Az alábbi példafát használjuk:

    <icestats>
        <admin>icemaster@localhost</admin>
        <client_connections>649</client_connections>
        <clients>2</clients>
        <connections>907</connections>
        <file_connections>379</file_connections>
        <host>localhost</host>
        <listener_connections>90</listener_connections>
        <listeners>0</listeners>
        <location>Earth</location>
        <server_id>Icecast 2.4.0</server_id>
        <source_client_connections>164</source_client_connections>
        <source_relay_connections>0</source_relay_connections>
        <source_total_connections>164</source_total_connections>
        <sources>2</sources>
        <stats>0</stats>
        <stats_connections>0</stats_connections>
        <source mount="/audio.ogg">
            <title>All that she wants</title>
            <artist>Ace of Base</artist>
            <audio_bitrate>499821</audio_bitrate>
            <audio_channels>2</audio_channels>
            <audio_info>samplerate=44100;quality=10%2e0;channels=2</audio_info>
            <audio_samplerate>44100</audio_samplerate>
            <channels>2</channels>
            <genre>various</genre>
            <ice-bitrate>499</ice-bitrate>
            <listener_peak>0</listener_peak>
            <listeners>0</listeners>
            <listenurl>http://localhost:8000/audio</listenurl>
            <max_listeners>unlimited</max_listeners>
            <public>1</public>
            <quality>10.0</quality>
            <samplerate>44100</samplerate>
            <server_description>Teststream</server_description>
            <server_name>Great audio stream</server_name>
            <server_type>application/ogg</server_type>
            <server_url>http://example.org/</server_url>
            <slow_listeners>0</slow_listeners>
            <source_ip>192.0.2.21</source_ip>
            <subtype>Vorbis</subtype>
            <total_bytes_read>3372153</total_bytes_read>
            <total_bytes_sent>0</total_bytes_sent>
            <user_agent>LadioCast/0.10.5 libshout/2.3.1</user_agent>
        </source>
        <source mount="/video.ogg">
            <audio_bitrate>276000</audio_bitrate>
            <audio_channels>6</audio_channels>
            <audio_samplerate>48000</audio_samplerate>
            <frame_rate>25.00</frame_rate>
            <frame_size>720 x 576</frame_size>
            <genre>various</genre>
            <ice-bitrate>276</ice-bitrate>
            <listener_peak>0</listener_peak>
            <listeners>0</listeners>
            <listenurl>http://localhost:8000/video</listenurl>
            <max_listeners>unlimited</max_listeners>
            <public>0</public>
            <server_description>Unspecified description</server_description>
            <server_name>Unspecified name</server_name>
            <server_type>video/ogg</server_type>
            <slow_listeners>0</slow_listeners>
            <source_ip>192.0.2.21</source_ip>
            <subtype>Vorbis/Theora</subtype>
            <title>ERAGON</title>
            <total_bytes_read>37136</total_bytes_read>
            <total_bytes_sent>0</total_bytes_sent>
            <user_agent>Lavf/55.20.0</user_agent>
            <video_bitrate>200000</video_bitrate>
            <video_quality>0</video_quality>
        </source>
    </icestats>
    

Általános statisztikák

• admin
  

  A szerver konfigurációjában beállított adminisztrátor elérhetősége. Általában e-mail cím, de lehet tetszőleges szöveg, pl. telefonszám is.

• client_connections
  

  Az összes klienskapcsolat száma (nem forrás). Ide tartoznak: hallgatók (nem párhuzamos, hanem összesített), admin funkciókhoz való hozzáférések és a statikus fájlkiszolgálás. Növekvő számláló.

• clients
  

  Az aktív klienskapcsolatok száma pillanatnyilag.

• connections
  

  Az összes bejövő TCP kapcsolat száma a szerver indulása óta. Növekvő számláló.

• file_connections
  

  A fájlkiszolgálási kérések száma. Növekvő számláló.

• host
  

  A konfigurációban megadott kiszolgálónév (DNS-ben feloldható teljes név vagy FQDN).

• listener_connections
  

  Hallgatói kapcsolatok száma a mountpontokhoz. Növekvő számláló.

• listeners
  

  Jelenleg aktív hallgatói kapcsolatok száma.

• location
  

  Szabad szövegmező, amely a szerver fizikai helyét vagy egyéb információt ír le. (Pl.: Budapest)

• server_id
  

  Alapértelmezésben az aktuális Icecast verziószám. Felülírható a konfigurációban.

• server_start_iso8601
  

  A szerver indulásának időbélyege ISO 8601 formátumban.

• server_start
  

  A szerver indulásának időbélyege RFC 2822 formátumban.
  Elavult, jövőbeni verziókban eltávolítható – helyette a server_start_iso8601 használata ajánlott.

• source_client_connections
  

  A forráskliens-csatlakozások száma a szerver indulása óta. Növekvő számláló.

• source_relay_connections
  

  Kimenő relay kapcsolatok száma más (mester) Icecast szerverekhez. Növekvő számláló.

• source_total_connections
  

  A forráskliens és relay kapcsolatok összesített száma. Növekvő számláló.

• sources
  

  Az aktuálisan csatlakozott források száma.

• stats
  

  Az aktív statisztikai kliensek száma.

• stats_connections
  

  A statisztikai kliensek összes csatlakozása a szerver indulása óta. Növekvő számláló.

Forrás-specifikus statisztikák

Fontos: ezek az értékek mindig az adott forrás aktuális kapcsolatára vonatkoznak. Ha a forrást bontja, majd újracsatlakozik, az adatok alaphelyzetbe állnak.

• artist
  

  Az aktuális dal előadója (a forrás kliens állítja be).

• title
  

  Az aktuális dal címe.

• audio_bitrate
  

  Hang bitráta (bit/s). Beállítható a forrás kliensből.

• audio_channels
  

  Audió csatornák száma.

• audio-info
  

  Információ a bitrátáról/mintavételi rátáról/minőségről. YP bejegyzéseknél is használatos.
  Példák:

• samplerate=44100;quality=10%2e0;channels=2 (LadioCast)
• ice-bitrate=128;ice-channels=2;ice-samplerate=44100 (Butt)
• ice-bitrate
  

  A stream bitrátája (kbit/s).

• samplerate
  

  Mintavételi ráta információ.

• quality
  

  A hangminőség jelző értéke.

• frame_rate
  

  Képkockasebesség. Csak videó streamnél.

• frame_size
  

  Képméret. Csak videó streamnél.

• video_bitrate
  

  Videó bitráta információ.

• video_quality
  

  Videó minőség jelző értéke.

• server_name
  

  A stream neve. Forrás kliens állítja be.

• server_description
  

  A stream leírása.

• server_type
  

  A stream MIME-típusa az adott mountponton.

• subtype
  

  MIME-altípus (pl. Opus, Vorbis, Theora). Több érték /-sel elválasztva.

• listener_peak
  

  A mountponton elért legmagasabb párhuzamos hallgatószám.

• listeners
  

  Az éppen aktív hallgatók száma.

• listenurl
  

  A mountpont URL-je. Az aliasokat nem veszi figyelembe.

• max_listeners
  

  Az adott mountponton engedélyezett hallgatók maximális száma.

• public
  

  Jelzi, hogy a mount megjelenik-e YP listákban. Forrás kliens állítja be, de a szerver felülírhatja.

• slow_listeners
  

  Lassú hallgatók száma.

• source_ip
  

  Az aktuális forrás kliens IP-címe. Relé esetén a <server> tartalma.

• stream_start_iso8601
  

  Az aktuális forrás kliens csatlakozásának időpontja ISO 8601 formátumban.

• stream_start
  

  Ugyanez RFC 2822 formátumban (elavult, jövőben eltávolítható).

• total_bytes_read
  

  A forrástól eddig fogadott bájtok száma.

• total_bytes_sent
  

  A hallgatóknak eddig elküldött bájtok száma (az aktuális forráscsatlakozás óta).

• user_agent
  

  A forrás kliens által küldött HTTP „User-Agent” fejléc.

Megjegyzés: További adatok elérhetők az admin felületen keresztül, mivel az adminisztráció minden oldala rendelkezik XML megfelelővel is.

7. Átirányítás (Relaying)

Áttekintés

A relézés (relaying) az a folyamat, amikor egy szerver tükröz egy vagy több streamet egy távoli szerverről. A szervereknek nem kell azonos típusúnak lenniük (például az Icecast tud relézni Shoutcast-ről is). A relézést elsősorban nagyobb közvetítéseknél használják, amikor a hallgató klienseket több fizikai gépre kell elosztani.

Relé típusok

Az Icecast kétféle relét támogat:

1. Mester–slave relé (master-slave relay)
   Ebben az esetben mind a mester, mind a slave szerver Icecast 2. Ilyenkor egy mester–slave relé állítható be, amihez csak annyi kell, hogy a slave szerver konfigurációjában megadjuk a mester szerver kapcsolati adatait (IP-cím és port). Ezután a slave tükrözni fogja a mester szerver összes mountpontját.
   A slave szerver időnként ellenőrzi is a mester szervert, hogy új mountpontok csatlakoztak-e, és ha igen, azokat is elkezdi relézni.
2. Egyedi közvetítés relé (single-broadcast relay)
   Ebben az esetben a slave szerverhez IP-címet, portot és mountpontot kell megadni, és csak az adott mountpont kerül relézésre.
   Ha egy Shoutcast szerveren lévő streamet szeretnénk relézni, akkor single-broadcast relét kell használnunk, és a mountpontot / értékre kell állítani.

Mester–slave relé beállítása

Ahhoz, hogy ilyen típusú relét állítsunk be, mindkét szervernek (a relézendőnek és a relézést végzőnek) Icecast 2 szervernek kell lennie. Példa konfiguráció:

    <master-server>192.168.1.11</master-server>
    <master-server-port>8001</master-server-port>
    <master-update-interval>120</master-update-interval>
    <master-password>hackme</master-password>
    

Ebben a példában a konfiguráció a relézést végző szerverben (slave) van megadva. A mester szervert nem kell külön reléként konfigurálni (sőt, nincs is tudomása arról, hogy relézik). Amikor a slave elindul, csatlakozik a 192.168.1.11:8001 címen lévő mester szerverhez, és elkezdi relézni az összes ott futó mountpontot. Emellett minden master-update-interval alatt (ebben a példában 120 másodpercenként) lekérdezi a mester szervert, hogy van-e új mountpont, és ha van, azt is relézni fogja.
Fontos: a slave szerveren a mountpontok nevei megegyeznek a mester szerveren lévő nevekkel.

Egyedi közvetítés relé (single-broadcast) beállítása

Ebben az esetben a mester szerver nem feltétlenül Icecast 2. Támogatott mester szerverek: Shoutcast, Icecast 1.x és természetesen Icecast 2. Példa konfiguráció:

    <relay>
        <server>192.168.1.11</server>
        <port>8001</port>
        <mount>/example.ogg</mount>
        <local-mount>/different.ogg</local-mount>
        <relay-shoutcast-metadata>0</relay-shoutcast-metadata>
    </relay>
    

Ebben a példában szintén a slave szerver konfigurációjában van megadva a relé. A mester szervert itt sem kell külön reléként beállítani (és nincs is tudomása arról, hogy relézik).
Amikor a slave elindul, csatlakozik a 192.168.1.11:8001 mester szerverhez, és csak az adott mountpontot (/example.ogg) relézi.

Ezzel a típusú relével a felhasználó felülírhatja a helyi mountpont nevét, így az a slave szerveren teljesen más is lehet, mint a mester szerveren.

Ha a mester egy Shoutcast szerver, akkor a <mount> értékének / kell lennie. Ha pedig szeretnénk, hogy a Shoutcast-relé stream tartalmazza a beágyazott metaadatokat is (mivel a Shoutcast a metaadatot közvetlenül a streambe ágyazza), akkor a <relay-shoutcast-metadata> értékét 1-re kell állítani.

8. YP könyvtárba listázás (Listing in a YP Directory)

Áttekintés

A YP (Yellow Pages) könyvtár egy olyan lista, amely a közvetített streameket tartalmazza.
Az Icecast 2 saját YP könyvtárral rendelkezik a következő címen: http://dir.xiph.org.

Jelenleg az Icecast csak az Icecast által támogatott YP könyvtárakban listázható. Ez azt jelenti, hogy nem tudod a stream-edet a Shoutcast YP könyvtárban közzétenni.

Az Icecast konfigurációs fájlja tartalmazza az összes elérhető YP könyvtár szervert. A stream YP-ben való listázása az Icecast konfigurációs fájl és a forrás kliens beállításainak kombinációjából áll.

Icecast beállítása YP támogatáshoz

Először is, az Icecast-ot YP támogatással kell fordítani.
Ez automatikusan megtörténik, ha a libcurl telepítve van. Ha a libcurl nem érhető el az Icecast fordításakor, akkor a YP támogatás le lesz tiltva.

Ha az Icecast YP támogatással lett fordítva, akkor a következő konfigurációs opciók vezérlik a YP könyvtár

    <directory>
        <yp-url-timeout>15</yp-url-timeout>
        <yp-url>http://dir.xiph.org/cgi-bin/yp-cgi</yp-url>
    </directory>
    

Több <directory> XML blokk is megadható, ha egyszerre több könyvtárban szeretnéd listázni a stream-et.

A forrás kliens beállítása YP támogatáshoz

Ez általában a forrás kliens dokumentációjában található meg.
Részletesebben: a forrás kliensnek a csatlakozáskor biztosítania kell a következő HTTP fejlécet: Ice-Public: 1

Ez szükséges ahhoz, hogy a stream YP listázása engedélyezve legyen.
Ez azonban felülírható a mountpont beállításaiban – lásd: Icecast Config File a további részletekért.
Ha egy mountpont YP-ben van listázva, akkor további statisztikák is megjelennek róla, például:

• last-touch
• currently-playing stb.

9. Hitelesítés (Authentication)

Hallgatói hitelesítés

A hallgatói hitelesítés az Icecast egyik funkciója, amely lehetővé teszi egy adott mountpont védelmét oly módon, hogy a hallgatónak valamilyen ellenőrzési teszten kell átmennie a hallgatás megkezdéséhez.
Ezzel a funkcióval például megvalósítható egy egyszerű fizetős hozzáférés (felhasználónév/jelszó párossal), vagy szűrés a hallgatói kapcsolatok alapján.
Ez a rész bemutatja ennek az összetevőnek az alapvető beállítását és kezelését.

A hallgatói hitelesítés meghatározásához a <mount> csoporton belül kell megadni bizonyos tageket, amelyek az adott mountponthoz kapcsolódnak.
Ez azt jelenti, hogy a hitelesítés érvényesíthető forrás kliensek vagy relék hallgatóira is.

A hallgatókra a következő hitelesítési mechanizmusok alkalmazhatók:

• htpasswd: egy megadott fájlban keresi a felhasználónév és jelszó páros egyezését
• URL: webes lekérdezéseket (pl. PHP) küld azonosításhoz

Az Icecast XML konfigurációban egy adott mounthoz rendelt hallgatói hitelesítés alkalmazható:

• forrás kliens streamjére,
• relére,
• vagy a webroot könyvtárban lévő fájlra.

Viszont nem vonatkozik az intro fájlokra vagy a fallback streamekre.

htpasswd Hallgatói hitelesítés

A hallgatói hitelesítés használatához mount-specifikus beállítást kell konfigurálnod.
Ez azt jelenti, hogy a fő Icecast konfigurációs fájlban létre kell hoznod egy <mount> szekciót.

Az alábbi egy példa:

    <mount>
        <mount-name>/example.ogg</mount-name>
        <authentication type="htpasswd">
            <option name="filename" value="myauth"/>
            <option name="allow_duplicate_users" value="0"/>
        </authentication>
    </mount>
    

A hallgatói hitelesítés támogatásához legalább a <mount-name> és az <authentication> mezőket meg kell adni.

• A mount-name az a mountpont neve, amelyhez a forrás kliensed csatlakozik.
• Az authentication határozza meg, hogy milyen típusú hitelesítőt használjon az Icecast.

Jelenleg csak a htpasswd és a url hitelesítők vannak megvalósítva.
Mindegyik hitelesítőnek változó számú kötelező opciója lehet, amelyeket az előző példában látható módon kell megadni.

A htpasswd hitelesítő a következő paramétereket igényli:

• filename – annak a fájlnak a neve, amely a felhasználóneveket és jelszavakat tartalmazza.
  Fontos megjegyezni, hogy ennek a fájlnak nem kell léteznie (és valószínűleg nem is fog, amikor először beállítod).
  Az Icecast beépített támogatást nyújt a felhasználók és jelszavak kezelésére a webes adminisztrációs felületen keresztül. Erről ebben a fejezetben később lesz szó.
• allow_duplicate_users – ha az értéke 0, akkor megakadályozza, hogy több kapcsolat használja ugyanazt a felhasználónevet.
  Ha az értéke 1, akkor engedélyez több kapcsolatot ugyanazzal a felhasználónévvel egy adott mountponton.
  Fontos: nincs lehetőség arra, hogy egy adott felhasználóhoz „maximális kapcsolatok számát” adj meg.

Az Icecast támogatja a hitelesítést igénylő és nem igénylő streamek vegyes használatát.

Felhasználók és jelszavak beállítása

Miután a megfelelő bejegyzéseket elvégezted a konfigurációs fájlban, csatlakoztasd a forrás klienst (az általad megadott mountponton keresztül).

A streamhez tartozó felhasználókat és jelszavakat a webes adminisztrációs felületen tudod beállítani.
Nyisd meg a következő címet:

    http://szerver:ip/admin/stats.xsl
    

Ha mindent helyesen konfiguráltál, egy ehhez hasonló képernyőt kell látnod.

Minden olyan mountpont előtt, amelyhez hallgatói hitelesítés van beállítva, egy lakat ikon jelenik meg.
Fontos megjegyezni, hogy ezen az oldalon csak a csatlakoztatott mountpontok fognak megjelenni.

A felhasználók és jelszavak kezeléséhez az adott mountponton kattints a „Manage Authentication” (Hitelesítés kezelése) linkre.
Ekkor a következő képernyő fog megjelenni:

Ez a képernyő megmutatja az adott mountponthoz beállított összes felhasználót.
Új felhasználó hozzáadása egyszerű: csak írd be a felhasználónevet és jelszót a mezőkbe, majd kattints az „Add” (Hozzáadás) gombra.

Fontos megjegyezni, hogy a felhasználóneveknek egyedinek kell lenniük, a jelszavakra viszont nincs korlátozás.
Felhasználót törölni az adott felhasználó mellett található delete (törlés) hivatkozásra kattintva lehet.

Befejezés

Ha létrehoztad a felhasználóidat, és mindent megfelelően beállítottál, akkor jöhet a bejelentkezés. Ehhez biztosítottunk egy egyszerű bejelentkező űrlapot, mely az alábbi útvonalon érhető el:

    http://szerver:port/auth.xsl
    

Az url egy olyan űrlapot jelenít meg, ahol a felhasználók beírhatják a felhasználónevüket és jelszavukat.

Ez az oldal egy m3u fájlt szolgál ki a felhasználónévvel és jelszóval, és a legtöbb esetben automatikusan megnyitja a megfelelő médialejátszót, majd elindítja a stream lejátszását.

URL

A hallgatók URL-alapú hitelesítése úgy történik, hogy amikor egy hallgató csatlakozik, az Icecast kéréseket küld egy webszervernek, és ellenőrzi a válaszfejléceket. Ha egy bizonyos fejléc visszaérkezik, akkor a hallgató folytathatja a kapcsolatot; ha nem, akkor a hallgató hibaüzenetet kap.

A megadott URL-ek olyan webszerver-szkripteket hívnak meg (pl. PHP), amelyek elvégzik a szükséges műveleteket. A szkriptnyelv egyetlen követelménye az, hogy képes legyen POST adatokat kezelni és válaszfejléceket visszaküldeni.
Az Icecast a libcurl könyvtárat használja a kérésekhez, így a HTTPS kapcsolatok is lehetségesek, de számolni kell a plusz erőforrásigénnyel.

Az egyes kérésekben a felhasználói ügynök (user-agent) az Icecast szerver verzióját jelöli. A válaszfejlécek döntik el, hogy a hallgató elfogadásra kerül-e. Ha a hallgató elutasításra kerül, akkor a válaszban ajánlott visszaküldeni a következő fejlécet, amely bekerül a naplófájlba:

    Icecast-Auth-Message: Ok
    

Az URL-alapú hitelesítés használatához mount-specifikus opciót kell megadni. Ez azt jelenti, hogy az Icecast fő konfigurációs fájlban létre kell hozni egy <mount> szekciót.

    <mount>
        <mount-name>/example.ogg</mount-name>
        <authentication type="url">
            <option name="mount_add" value="http://auth.example.org/stream_start.php"/>
            <option name="mount_remove" value="http://auth.example.org/stream_end.php"/>
            <option name="listener_add" value="http://auth.example.org/listener_joined.php"/>
            <option name="listener_remove" value="http://auth.example.org/listener_left.php"/>
            <option name="username" value="user"/>
            <option name="password" value="pass"/>
            <option name="auth_header" value="icecast-auth-user: 1"/>
            <option name="timelimit_header" value="icecast-auth-timelimit:"/>
            <option name="headers" value="x-pragma,x-token"/>
            <option name="header_prefix" value="ClientHeader."/>
            <option name="stream_auth" value="http://auth.example.org/source.php"/>
        </authentication>
    </mount>
    

Az opciókat az alábbiakban részletesebben ismertetjük, melyek opcionálisak és minden esetben a POST adatokon belül az egyes beállítások értéke kódolva van.

• mount_add
  

  Ez az URL értesíti a hitelesítő szervert egy stream elindulásáról.
  Ilyenkor hallgatói adatok nem kerülnek továbbításra, de a hitelesítő szerver inicializálhat bármilyen információt.

POST adatok

• action = mount_remove
• mount = a megszűnő mountpont
• server = a szerver neve (<hostname>)
• port = a szerver portja

Példa:

    action=mount_add&mount=/live&server=icecast.example.org&port=8000
    

• mount_remove
  

  Ez az URL értesíti a hitelesítő szervert egy stream befejeződéséről. Hallgatói adatok itt sem kerülnek átadásra.

POST adatok

• action = mount_add
• mount = az induló mountpont
• server = a szerver neve (<hostname>)
• port = a szerver portja

Példa:

    action=mount_remove&mount=/live&server=icecast.example.org&port=8000
    

• listener_add
  

  Ez a leggyakrabban használt beállítás.
  Amikor egy hallgató csatlakozik, mielőtt bármi adatot kapna, ez a kérés lefut.
  Alapértelmezésben a hallgató elutasításra kerül, hacsak a hitelesítő szerver vissza nem küldi a megfelelő fejlécet (pl. auth_header).

POST adatok

• action = listener_add
• mount = a mountpont (lekért URL a query paraméterekkel együtt)
• server = a szerver neve (<hostname>)
• port = a szerver portja
• user = hallgató felhasználóneve (HTTP basic auth), üres is lehet
• pass = hallgató jelszava (HTTP basic auth), üres is lehet
• client = az Icecast által adott egyedi kliensazonosító
• ip = a hallgató IP címe
• agent = a hallgató médialejátszójának user-agent értéke

Példa:

    action=listener_add&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&ip=127.0.0.1&agent=My%20player
    

• listener_remove
  

  Ez az URL akkor hívódik meg, amikor egy hallgató kapcsolatot bont.

POST adatok

• action = listener_remove
• mount = a mountpont neve
• server = a szerver neve (<hostname>)
• port = a szerver portja
• user = hallgató felhasználóneve (HTTP basic auth), üres is lehet
• pass = hallgató jelszava (HTTP basic auth), üres is lehet
• client = az Icecast által adott egyedi kliensazonosító
• ip = a hallgató IP címe
• agent = a hallgató médialejátszójának user-agent értéke
• duration = másodpercben, mennyi ideig volt csatlakozva

Példa:

    action=listener_remove&server=icecast.example.org&port=8000&client=1&mount=/live&user=&pass=&duration=3600&ip=127.0.0.1&agent=My%20player
    

• stream_auth
  

  Bár ez technikailag nem a hallgatók, hanem a források hitelesítéséhez tartozik, hasonlósága miatt itt is szerepel.
  Amikor egy forrás (pl. egy adás) csatlakozik, mielőtt bármi adatot küldene, ez a kérés lefut.
  Alapértelmezésben a forrás elutasításra kerül, hacsak a hitelesítő szerver nem küld vissza egy megfelelő fejlécet.

POST adatok

• action = stream_auth
• mount = a mountpont neve
• server = a szerver neve (<hostname>)
• port = a szerver portja
• user = a forrás kliens által küldött felhasználónév
• pass = a forrás kliens által küldött jelszó
• admin = adminisztratív kérés (pl. metainformáció frissítése esetén 1)

Példa:

    action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1
    

Egyéb opciók

• auth_header
  

  A válaszban elvárt fejléc, amely engedélyezi a hitelesítést.
  Alapértelmezett érték:

    icecast-auth-user: 1
    

• De lehet más is, például:
  

    HTTP 200 OK
    

• timelimit_header
  

  Meghatározható vele, hogy a hallgatók mennyi ideig maradhatnak csatlakozva.
  Ha a válaszban ez a fejléc szerepel egy másodpercekben megadott számmal, akkor a kliens ennyi idő után lecsatlakozik.

• headers
  

  Az ügyfél által küldött HTTP-fejlécek listája, amelyeket tovább kell adni a hitelesítő szolgáltatásnak.
  Ezek elé automatikusan hozzáfűződik a header_prefix értéke, és POST paraméterként kerülnek átadásra.

• header_prefix
  

  Az a prefix, amivel a kliens fejléceit továbbítja a rendszer. (Lásd: headers.)

Megjegyzés a lejátszókról és a hitelesítésről

Nem rendelkezünk teljes listával azokról a lejátszókról, amelyek támogatják a hallgatói hitelesítést. Az Icecast szabványos HTTP Basic Authentication-t használ, és általánosságban elmondható, hogy sok médialejátszó támogatja ezt, ha egyáltalán bármilyen hitelesítést kezel.

A Windows rendszeren a Winamp és a Foobar2000 támogatja a HTTP Basic Authentication-t, míg UNIX platformokon az XMMS biztosítja ezt.
A Winamp és az XMMS legalább a lekérdezési paraméterek (query parameters) átadását is támogatják, és elképzelhető, hogy más lejátszók is.
Részletekért lásd a HTTP-fejléceket.

Forrás-hitelesítés

A forrás-hitelesítés az Icecast egyik funkciója, amely lehetővé teszi, hogy egy adott mountpontot biztonságossá tegyél. Így ahhoz, hogy egy kliens oda streamelhessen, először egy ellenőrzési folyamaton kell átmennie.
Ez a szakasz bemutatja a komponens beállításának és karbantartásának alapjait.

A forráshitelesítést a szekción belül lehet meghatározni, a mountponthoz kapcsolódó tagekkel.

A forrásokhoz alkalmazható hitelesítési mechanizmusok:

• BASIC:<password> és esetleg <username> a <mount> szekcióban
• URL: webes kérések (pl. PHP) küldése azonosítás céljából
• URL-alapú hitelesítés: stream_auth

Egy <mount> szekció tartalmazhat egy <authentication type="url"> részt, amelyben például:

    <option name="stream_auth" value="http://auth.example.org/source.php"/>
    

Amikor egy forrás csatlakozik, mielőtt bármi visszaküldésre kerülne, ez a kérés feldolgozásra kerül.
Az alapértelmezett működés az, hogy a forrás elutasításra kerül, hacsak az autentikációs szerver nem küld vissza egy megfelelő válaszfejlécet. (Ez ugyanaz a mechanizmus, mint a hallgatói hitelesítésnél.)

POST adatok

• action = stream_auth
• mount = a mountpont neve
• server = a szerver neve (<hostname>)
• port = a szerver portja
• user = a forrás kliens által küldött felhasználónév
• pass = a forrás kliens által küldött jelszó
• admin = adminisztrációs kérés (lásd lejjebb)

Megjegyzés: Adminisztrációs kérések érkezhetnek a streamhez (például metainformációk frissítése). Ezek a kérések akkor is kiadhatók, amikor a stream már aktív. Ilyenkor a POST adatokban az admin értéke 1.

Példa:

    action=stream_auth&mount=/stream.ogg&ip=192.0.2.0&server=icecast.example.org&port=8000&user=source&pass=password&admin=1
    

10. Win32 specifikus dokumentáció (Win32 specific documentation)

Win32 sajátosságok

Az Icecast 2 Win32-re írt változata egy egyszerű parancssoros alkalmazás. Korábban volt körülötte egy grafikus felület is, amely az Icecast 2 szerver magjára épült.

Az Icecast 2 legtöbb funkciója elérhető a Win32 változatban is, viszont jelentős hiányosság az IPv6 támogatás.

Ha elegendő felhasználói igény mutatkozik, újra bevezethetjük az Icecast grafikus felületét, illetve azt a lehetőséget, hogy az Icecast Windows-szolgáltatásként fusson.

11. Szójegyzék (Glossary)

• Forrás kliens (Source client)
  

  A forrás kliens egy külső program, amely felelős azért, hogy a tartalmat (adatfolyamot) elküldje az Icecast szervernek.
  Néhány forrás kliens, amely támogatja az Icecast 2-t: Oddcast, Ices 2, Ices 0.3 és DarkIce.

• Alárendelt szerver (Slave server / Relay)
  

  Egy relé konfigurációban az alárendelt szerver az a szerver, amely az adatot a mester szervertől húzza le. Úgy működik, mint egy hallgató kliens a mester szerver felé.

• Mester szerver (Master server / Relay)
  

  Egy relé konfigurációban a mester szerver az a szerver, amely tartalmazza azt a streamet, amelyet az alárendelt szerverek átvesznek.

• Mountpont (Mountpoint)
  

  A mountpont az Icecast szerveren egy erőforrás, amely egyetlen adásfolyamot képvisel. A mountpontokat fájlokhoz hasonló módon nevezik el (pl. /mystream.ogg, /mymp3stream).
  Amikor a hallgatók csatlakoznak az Icecast-hoz, meg kell adniuk a mountpontot a kérésben (pl. https://freestream.hu:8340/ebm).
  Ugyanígy a forrás klienseknek is meg kell adniuk egy mountpontot, amikor csatlakoznak.
  A statisztikák mountpontonként kerülnek nyilvántartásra.
  A mountpontok alapvető elemei az Icecast 2 működésének és felépítésének.

• Tartalék mountpont (Fallback mountpoint)
  

  A tartalék mountpont egy szülő mountponthoz van hozzárendelve. Ha a szülő mountpont elveszíti a kapcsolatot az Icecast-tal, akkor az Icecast automatikusan áthelyezi az összes jelenleg csatlakozott klienst a kiesett mountpontról a tartalék mountpontra.

12. Gyakran ismételt kérdések (FAQ)

Általános kérdések

Mi az az Icecast.org?

Az Icecast.org projekt olyan programok és könyvtárak gyűjteménye, amelyek interneten keresztüli hangstreamelést tesznek lehetővé. Ezek közé tartozik:

• Icecast – egy program, amely hangadatokat sugároz a hallgatóknak
• libshout – egy könyvtár, amely az Icecast szerverekkel való kommunikációt biztosítja
• IceS – egy program, amely hangadatokat küld az Icecast szerverekre

A forrás kliens egy külső program, amely felelős a tartalom (hangadat) Icecasthoz történő továbbításáért. Az Icecast 2-t támogató forrás kliensek például: Oddcast, Ices 2, Ices 0.3 és DarkIce.

Mi az az Icecast program?

Az Icecast olyan program, amely hangot sugároz a hallgatók számára, és kompatibilis a Nullsoft Shoutcast rendszerével.

Mi az a libshout?

A libshout egy könyvtár, amely kommunikál és adatot továbbít egy Icecast szerver felé. Kezeli a socket kapcsolatot, az adatátvitel időzítését, valamint megakadályozza a hibás adatok továbbítását a szerverre.

Mi az az Ices?

Az Ices egy forrás kliens program, amely hangadatokat küld egy Icecast szervernek, hogy aztán a hallgatókhoz sugározhassa.
Az Ices képes:

• lemezről olvasni hangfájlokat (például Ogg Vorbis fájlokat), vagy
• élő hangot mintavételezni egy hangkártyáról, és azt valós időben kódolni.

Mivel hallgathatok egy Icecast streamet?

Az Icecast-kompatibilis médialejátszók listáját az icecast.org weboldalon tartjuk karban.