Best OScam Reader Setup: oscam.server Config Guide 2026

If you've ever stared at a fresh oscam.server file wondering why half the parameters even matter, you're not alone. Most guides just paste a working block and tell you to swap in your own credentials. That gets you connected. It doesn't get you decoding reliably, and it definitely doesn't explain why your reader shows "CARD OK" while every channel still throws an ECM error.

This is my attempt at an actual oscam reader setup best walkthrough — not a copy-paste block, but the reasoning behind each line so you can debug it yourself six months from now when something breaks at 2am. I've run OScam on everything from a Raspberry Pi 3 to a dedicated VPS, and the failure patterns repeat themselves constantly. Let's get into the file structure first, because that's where most confusion starts.

What an OScam Reader Actually Is (and How It Differs From an Account)

People throw around "account," "line," and "reader" like they're interchangeable. In OScam they're not. A reader is a source of ECM/EMM decoding — full stop. It can be a physical smartcard sitting in a Phoenix or Smargo device plugged into your box, or it can be a remote connection to someone else's card over a network protocol. Either way, from OScam's perspective, a reader is just something it can ask "can you decode this ECM for me?"

The confusion usually comes from mixing up the three config files that make an OScam install work. oscam.conf holds global settings — load balancing mode, logging, webif ports, that kind of thing. oscam.user defines the clients you serve, meaning the boxes or software connecting to your OScam instance. And oscam.server is where readers live — every card source, local or remote, gets a [reader] block in this file. Get this separation wrong and you'll spend hours editing the wrong file wondering why nothing changes.

Reader vs. account vs. user: the three config files

Think of it as a pipeline. A client connects using credentials defined in oscam.user. That user is assigned to a group. OScam then looks at oscam.server for any reader that shares that same group number and is capable of decoding the requested caid. If it finds one, the ECM gets forwarded to that reader — whether it's a local card or a peer three hops away — and the decoded CW comes back down the chain to the client.

That group linkage is the single most overlooked piece in every "oscam reader setup best" tutorial I've read. People configure a perfect reader block, forget to set the group number to match their user, and then spend an hour troubleshooting a phantom connection issue that was never a connection issue at all.

Local card readers vs. network (proxy) readers

A local reader talks to physical hardware — device = /dev/ttyUSB0 for a serial Phoenix reader, for example, with detect=CD or similar. A network reader, sometimes called a proxy reader, connects over TCP/IP to a remote OScam or CCcam server using a protocol like cccam, newcamd, or cs378x. Most people setting up cardsharing today are dealing almost entirely with network readers, since actual physical smartcard hardware has become less common outside of dedicated card farms.

Where readers live: oscam.server and its role in the pipeline

Every reader gets its own [reader] section in oscam.server, identified by a unique label. OScam parses this file at startup (or on reload via webif) and attempts to establish each reader connection independently. The "best" setup here isn't about cramming in every optional parameter — it's about writing tight, minimal, correctly scoped entries so OScam never wastes time or bandwidth querying a source that can't possibly answer.

Building the Ideal Network Reader in oscam.server

Here's a full annotated example for a cccam-protocol reader. I'll break down every line after.

[reader]label = provider1_hdprotocol = cccamdevice = 185.23.xx.xx,12000user = myusernamepassword = mypasswordgroup = 1caid = 0100,0500,0B00ident = 0100:XXXXXX,0500:YYYYYYcccversion = 2.3.2cccmaxhops = 2cccwantemu = 0inactivitytimeout = 30reconnecttimeout = 15ecmtimeout = 3000audisabled = 1

The device line is host,port — and I want to be clear, there's no universal standard port for cardsharing protocols. You'll see 12000 used commonly for cccam and something in the 5000s or 8000s range for newcamd or cs378x, but these are entirely operator-defined. Whoever runs the source tells you the port. Don't assume 12000 works everywhere just because it's common.

Full [reader] block: label, protocol, device, user, password, key

label is just an internal identifier — make it descriptive, since you'll be reading it in logs constantly. protocol tells OScam which handshake to use. device is host,port for network readers. user and password are your login credentials. For newcamd readers you'll also need a key= line holding the DES key, which I'll get to in a second because it trips up a lot of people.

Choosing protocol: cccam vs. newcamd vs. cs378x vs. mgcamd

cccam is the most common protocol for peer-to-peer sharing because so many boxes and panels speak it natively. newcamd is older but still widely supported, and it requires a DES key exchange — typically a 14-byte hex key, and if you paste it wrong (too short, extra whitespace, wrong case) the reader will often just sit there failing silently instead of throwing an obvious error.

cs378x is worth knowing about specifically if you're connecting two OScam boxes together — it's essentially camd35 over TCP with added message integrity checking, versus the older UDP-based camd35 which has none. If both ends run OScam, cs378x or newcamd tend to be cleaner and lower-overhead than cccam. mgcamd support exists mostly for backward compatibility with older boxes that only speak newcamd/cccam variants — you won't set protocol=mgcamd in oscam.server itself, since mgcamd is a client-side application, not an OScam reader protocol.

group, caid, ident and label routing for clean decode paths

This is the part almost every guide skips, and it's exactly why so many people end up with a reader that connects fine but never decodes anything. group ties the reader to specific users — if your user in oscam.user has group = 1 and your reader has group = 1, OScam considers that reader eligible to serve that client. No shared group number, no ECM ever reaches that reader, regardless of how correctly everything else is configured.

caid restricts which encryption systems the reader gets queried for. If you know your source only carries Viaccess (0500) and Nagravision (0100), don't leave caid blank — set it explicitly. ident goes a level deeper, narrowing to specific provider IDs within a caid, formatted as caid:ident pairs. Filtering aggressively here isn't just tidy configuration — it directly reduces ECM errors, because OScam stops wasting cycles asking a reader for channels it was never going to answer for in the first place.

cccversion, cccmaxhops, cccwantemu explained

cccversion needs to match what the peer expects — 2.3.0 and 2.3.2 are the common versions floating around. Mismatch this and you'll often see the reader connect successfully but report a wrong card count, or zero shares at all, which looks like a permissions problem but is actually a protocol handshake mismatch. cccmaxhops caps how many resharing hops away a card can be and still get accepted — lower values mean you're closer to the source card, generally faster and more stable. cccwantemu controls whether you want emulated/softcam-based cards included; leave it at 0 unless you specifically want those included in your feed.

Best-Practice Reader Tuning: Timeouts, Caching, Fallback, and Hops

Gdy czytnik już się połączy i dekoduje, kolejną warstwą jest strojenie — to właśnie tutaj zwykle działająca konfiguracja zamienia się w naprawdę niezawodną best configuration czytnika oscam reader, która przetrwa godziny szczytu i przełączanie kanałów bez zacinania się.

ecmtimeout / ecmwhitelist i dlaczego 3000ms to dobry punkt startowy

ecmtimeout określa, jak długo OScam czeka na odpowiedź czytnika, zanim się podda i spróbuje fallbacku. 3000ms to rozsądny punkt startowy dla większości zdalnych źródeł. Ustawisz za nisko i dostaniesz przedwczesny fallback — czytnik miał zaraz odpowiedzieć, ale połączenie zostało przerwane, co powoduje niepotrzebne opóźnienia przy zapowaniu i marnowanie CPU, bo OScam próbuje gdzie indziej. Ustawisz za wysoko i masz odwrotny problem: widoczne zamrożenia obrazu, podczas gdy OScam cierpliwie czeka na wolny lub martwy czytnik, zanim w końcu przejdzie na fallback.

fallback i fallback_percaid dla redundancji

Czytnik zapasowy jest odpytywany dopiero po tym, jak główny zawiedzie lub przekroczy limit czasu — nie służy do balansowania obciążenia, to ubezpieczenie. Skonfiguruj to w oscam.user lub za pomocą ustawień fallback uwzględniających lb_mode, a fallback_percaid użyj, gdy chcesz innego zachowania fallbacku dla poszczególnych systemów szyfrowania, zamiast jednego uniwersalnego czytnika zapasowego dla wszystkiego.

tryby cacheex 1/2/3 i kiedy czytnik powinien wypychać (push), a kiedy pobierać (pull)

Wymiana cache jest naprawdę przydatna do przyspieszania powtórnych dekodowań w sieci wielu boxów, ale to też miejsce, w którym widziałem konfiguracje, które kompletnie się rozsypały. Tryby: 1 to tylko push, 2 to tylko pull, 3 to push i pull w obie strony. Błąd, który ludzie popełniają bez przerwy, to ustawianie cacheex mode 3 po obu stronach relacji peer — tworzy to pętlę, w której każda strona ciągle wypycha te same wpisy cache z powrotem do drugiej, zalewając logi, a czasem zamrażając cały łańcuch.

Poprawny wzorzec jest asymetryczny. Jeśli box A jest twoim głównym, a box B chce cache z A, B powinien mieć ustawiony cacheex mode 2 (pull) w kierunku A, a A nie powinien jednocześnie mieć ustawionego pobierania od B dla tego samego caid/danych. Jeśli nie rozwiązujesz aktywnie konkretnego problemu z opóźnieniami, zostaw cacheex wyłączony. To nie jest funkcja domyślnie włączona — to celowa optymalizacja dla konkretnych topologii sieciowych.

lb_weight, lb_force_fallback i globalna strategia loadbalance

Samo balansowanie obciążenia jest konfigurowane globalnie w oscam.conf za pomocą lb_mode — tryb 1 wybiera najszybszy czytnik na podstawie zmierzonego czasu odpowiedzi. Ale poszczególne czytniki mają lb_weight, który wpływa na to, jak często OScam wybiera dany czytnik względem innych obsługujących ten sam caid. Jeśli masz dwa czytniki, oba zdolne do dekodowania tego samego caid i oba o zbliżonej szybkości, możesz skończyć z OScam przeskakującym między nimi, co objawia się skrajnie niespójnymi czasami dekodowania w webif od jednego zapowania do drugiego. Ustawienie wyraźnej różnicy lb_weight — powiedzmy 100 na preferowanym czytniku i 50 na zapasowym — mówi OScam, który czytnik faktycznie preferować, zamiast traktować je jako równorzędne.

audisabled, aureader i obsługa EMM

audisabled=1 mówi OScam, żeby nie przetwarzał aktualizacji EMM przez ten czytnik — to znaczy, że nie będzie próbował zapisywać pakietów aktualizacyjnych z powrotem na kartę. Ma to duże znaczenie przy lokalnych fizycznych kartach: jeśli masz kilka czytników jakoś skierowanych na tę samą fizyczną kartę (nietypowe, ale zdarza się przy niektórych konfiguracjach multi-client), pozwolenie więcej niż jednemu na jednoczesny zapis EMM może naprawdę uszkodzić wewnętrzny stan karty. Rozwiązanie jest proste — wybierz jeden czytnik jako ten zapisujący EMM i ustaw audisabled=1 na każdym innym czytniku dotykającym tej samej karty.

Weryfikacja i rozwiązywanie problemów z czytnikiem, który nie dekoduje

Oto kolejność diagnostyczna, której faktycznie używam za każdym razem, zanim dotknę choćby jednej wartości konfiguracyjnej.

Czytanie oscam.log i strony Readers/Status w webif

Pierwszym przystankiem jest zawsze zakładka Readers w webif. Status pokazuje zielony dla połączonych, czerwony dla niepołączonych. Jeśli jest czerwony, to czysto problem na warstwie połączenia — nie trać czasu na sprawdzanie filtrów caid. Sprawdź osiągalność hosta/portu, upewnij się, że firewall zezwala na wychodzący TCP na tym porcie, zweryfikuj nazwę użytkownika/hasło i potwierdź, że wersja protokołu zgadza się z tym, czego oczekuje druga strona.

Połączony, ale 'CARD OK' bez dekodowania: niezgodność filtra caid/ident

Jeśli status pokazuje połączony i nawet „CARD OK”, ale konkretne kanały nadal się nie dekodują, to prawie nigdy nie jest problem z połączeniem. Wróć do swoich linii caid= i ident= i sprawdź, czy przypadkiem nie wykluczyłeś caid, którego używa dany kanał. Sprawdź też dokładnie, czy numer grupy faktycznie zgadza się między czytnikiem a żądającym użytkownikiem — naprawiałem dokładnie ten problem więcej razy, niż jestem w stanie zliczyć, i zawsze chodzi o jedną z tych dwóch rzeczy.

'connected' migające: niezgodność wersji lub hasła/klucza DES

Czytnik, który się łączy, potem rozłącza, a potem ponownie łączy kilka sekund później — wielokrotnie — zazwyczaj wskazuje na niezgodność cccversion lub, w newcamd, źle sformułowany klucz DES. Sprawdź dokładnie długość klucza; powinien mieć dokładnie 14 bajtów hex bez żadnych zbędnych znaków. Jeśli czytnik pozostaje połączony tylko zaraz po restarcie OScam, a potem się rozłącza wkrótce potem, sprawdź swoje wartości reconnecttimeout i inactivitytimeout — zbyt agresywny timeout zerwie połączenia, które są w rzeczywistości w porządku, tylko chwilowo bezczynne.

Błędy ECM, przekroczenia czasu ECM i diagnoza 'no matching reader'

„No matching reader” w logu oznacza, że OScam nie znalazł żadnego czytnika we właściwej grupie z właściwym zakresem caid/ident dla tego ECM — sprawdź ponownie swoje filtry. Rzeczywisty timeout ECM w logu (w przeciwieństwie do odrzucenia) oznacza, że czytnik był osiągalny i w zakresie, ale nie odpowiedział na czas, co wskazuje z powrotem na dostrojenie ecmtimeout lub rzeczywiste opóźnienia sieciowe do tego źródła.

Bezpieczne używanie loglevel w oscam.log i flag debugowania -d

loglevel w oscam.conf kontroluje szczegółowość logów — zwiększ ją tymczasowo, gdy tropisz konkretny problem, ale nie zostawiaj logowania na poziomie debug uruchomionego na stałe, ponieważ rozdmucha to pliki logów i może przysłonić rzeczywistą linię błędu w szumie. Użyj flag -d (jak -d 1 dla debugu klienta, -d 2 dla debugu czytnika) z linii poleceń na krótką sesję diagnostyczną, a potem zmniejsz ją z powrotem, gdy już znajdziesz to, czego szukałeś.

Jak ogólnie ocenić źródło kart (bez nazw)

Nie powiem ci, którego dostawcę używać — to tak naprawdę nie jest sens dobrego tekstu technicznego, a poza tym i tak nie zestarzałoby się to dobrze. Powiem ci za to dokładnie, co mierzyć, żebyś mógł sam ocenić dowolne źródło, używając niczego więcej niż własnego webif OScam.

Sygnały stabilnego źródła: spójny czas dekodowania, niski % błędów ECM

Otwórz stronę statusu Readers i obserwuj kolumnę średniego czasu dekodowania przez cały wieczór rzeczywistego użytkowania, nie tylko pięciominutowy test. Wszystko konsekwentnie poniżej 300ms jest solidne. Jeśli widzisz dzikie wahania — raz 150ms, za chwilę 2000ms — to źródło o niestabilnej mocy backendu, i objawi się to zamrażaniem podczas szybkiej zmiany kanałów, nawet jeśli „działa” w szybkim teście.

Przejrzystość protokołu/wersji i dopasowany cccversion

Dobrze prowadzone źródło mówi ci dokładnie, jaki protokół, port i wersję ustawić — bez zgadywania. Jeśli źródło jest niejasne co do tego, jaki cccversion ustawić, albo musisz ciągle metodą prób i błędów szukać portu, to już sygnał o tym, jak cała ta operacja jest prowadzona.

Liczba przeskoków, głębokość udostępniania i dlaczego mniejsza liczba przeskoków dekoduje szybciej

Liczba przeskoków (hop count) mówi, ile razy karta była już reshareowana, zanim dotarła do Ciebie. Hop 1 oznacza, że rozmawiasz z czymś bliskim faktycznej karcie. Wyższa liczba przeskoków oznacza więcej warstw resharingu między Tobą a źródłem, co zazwyczaj oznacza większe opóźnienia i więcej potencjalnych punktów awarii. To naprawdę jedna z bardziej użytecznych, mierzalnych wartości, jakie masz do dyspozycji, i jest widoczna wprost w szczegółach czytnika w webif.

Czerwone flagi: wymuszona wysoka liczba przeskoków, niestabilne ponowne połączenia, EMM wyłączone wszędzie

Zwracaj uwagę na źródła, które wymuszają nietypowo wysoką liczbę przeskoków bez wyjaśnienia, czytniki, które ciągle się przełączają na nowo bez wyraźnej przyczyny sieciowej po Twojej stronie, lub konfiguracje, w których obsługa EMM wygląda na całkowicie wyłączoną na całej linii, bez jakiejkolwiek ścieżki aktualizacji karty. Żadna z tych rzeczy sama w sobie automatycznie nie dyskwalifikuje źródła, ale razem tworzą obraz, na który warto zwrócić uwagę, zanim poświęcisz na to realny czas konfiguracji.